OpenCode#

OpenCode is an open source, terminal-first AI coding agent available in Bluefin as part of the Bluespeed AI tooling suite. It ships two distinct packages: a CLI (opencode) for headless/TUI use and a desktop client (opencode-desktop-linux) for a GUI-wrapped experience. It is distinct from Goose (Bluefin's primary AI agent), RamaLama (local LLM backend), and the broader AI Integration layer.

Installation#

Both packages are bundled in the ai-tools.Brewfile and installed via:

ujust bbrew # select the "ai" bundle

Package	Type	Tap	Notes
`anomalyco/tap/opencode`	`brew` (CLI/TUI)	`anomalyco/tap`	Stable
`ublue-os/experimental-tap/opencode-desktop-linux`	`cask` (desktop app)	`ublue-os/experimental-tap`	Experimental

The desktop cask (opencode-desktop-linux) was introduced at v1.1.15 and lives in the experimental tap. The CLI is available on Homebrew formulae directly.

Note: autoupdate in OpenCode's own config only works when installed outside of a package manager — when installed via Homebrew, updates come through brew upgrade.

Configuration#

OpenCode uses JSON or JSONC (JSON with Comments) files validated against the schema at opencode.ai/config.json.

Config file locations (in precedence order)#

Priority	Location	Purpose
1 (lowest)	Remote `.well-known/opencode`	Org-wide defaults
2	`~/.config/opencode/opencode.json`	Global user config
3	`OPENCODE_CONFIG` env var	Custom path override
4	`opencode.json` in project root	Per-project settings
5	`.opencode/` directories	Agents, commands, plugins
6	`OPENCODE_CONFIG_CONTENT` env var	Inline runtime override
7	`/etc/opencode/opencode.json` (Linux)	Admin-enforced, non-overridable

Configs are merged, not replaced — non-conflicting keys from all sources are preserved.

Key config options#

Key	Purpose	Example value
`model`	Primary model	`"anthropic/claude-sonnet-4-5"`
`small_model`	Lightweight tasks (title gen, etc.)	`"anthropic/claude-haiku-4-5"`
`permission`	Tool approval gates	`{"bash": "ask", "edit": "ask"}`
`mcp`	MCP server connections	see MCP section below
`autoupdate`	Self-update on launch	`false` (when using Homebrew)
`share`	Conversation sharing	`"manual"` / `"auto"` / `"disabled"`
`lsp`	LSP server integration	`true`
`snapshot`	Undo/revert tracking	`true` (default)
`default_agent`	Default built-in agent	`"build"` / `"plan"`
`disabled_providers`	Block specific providers	`["openai"]`

See the full config reference for all options.

Permissions#

By default, OpenCode allows all operations without prompting. Gate specific tools with "ask" or "deny":

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": "ask",
    "edit": "ask"
  }
}

MCP Integration#

OpenCode supports Model Context Protocol servers natively via the mcp key. To connect the linux-mcp-server (also available in the ai-tools bundle at line 16 of the Brewfile ):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "linux-tools": {
      "type": "local",
      "command": ["linux-mcp-server"],
      "enabled": true
    }
  }
}

Remote MCP servers (with OAuth) are also supported via "type": "remote" and a URL.

TUI-specific config#

TUI settings (themes, keybinds, scroll, notifications) live in a separate tui.json file alongside opencode.json, validated against opencode.ai/tui.json. Legacy theme/keybinds/tui keys in opencode.json are deprecated.

Reference Links#

Resource	URL
OpenCode homepage	https://opencode.ai/
Full config docs	https://opencode.ai/docs/config/
Config JSON schema	https://opencode.ai/config.json
TUI docs	https://opencode.ai/docs/tui/
MCP server docs	https://opencode.ai/docs/mcp-servers/
Agents docs	https://opencode.ai/docs/agents/
Bluefin AI guide	https://docs.projectbluefin.io/ai
ai-tools.Brewfile	projectbluefin/common