OpenCode

Open-source AI coding agent in the terminal. Built by Anomaly, 100% provider-agnostic.

Official docs · GitHub

Install

1

$ curl -fsSL https://opencode.ai/install | bash

1

$ brew install anomalyco/tap/opencode

1

$ npm install -g opencode-ai@latest

1
2

$ sudo pacman -S opencode      # Stable
$ paru -S opencode-bin          # Latest (AUR)

1
2

$ scoop install opencode
$ choco install opencode

1

$ nix run nixpkgs#opencode

A desktop app is also available at opencode.ai/download.

Launch & authenticate

1

$ opencode

On first launch, use /connect to add a provider and enter your API key. OpenCode supports 75+ providers via the AI SDK.

Alternatively, set API keys via environment variables:

Agents

OpenCode includes built-in agents you can switch between with Tab.

Primary agents

Subagents

Invoked automatically (via the task tool) or with an @mention in messages, e.g. @general. Each runs in a child session: enter it with Ctrl+X Down, cycle siblings with Left / Right, go back to the parent with Up.

Custom agents

Define custom agents in opencode.json, as markdown files in .opencode/agents/ (project) or ~/.config/opencode/agents/ (global), or interactively with opencode agent create:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-5-5",
      "prompt": "{file:./prompts/review.txt}",
      "permission": { "edit": "deny", "bash": "ask" }
    }
  }
}

The old tools map is deprecated — restrict an agent with permission instead. hidden: true hides a subagent from the @ menu.

Keyboard shortcuts

OpenCode uses a leader key (default: Ctrl+X) for most shortcuts. Press the leader, then the action key.

Slash commands

Configuration

OpenCode uses JSON (or JSONC) config files, merged in this order (later overrides earlier):

1. Remote config (.well-known/opencode)
2. Global: ~/.config/opencode/opencode.json
3. Custom: $OPENCODE_CONFIG
4. Project: opencode.json in project root

TUI-specific settings go in a separate tui.json.

Example config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "autoupdate": true,
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000
      }
    }
  }
}

TUI config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "mouse": true,
  "scroll_speed": 3,
  "diff_style": "auto",
  "keybinds": {
    "leader": "ctrl+x"
  }
}

Workflow: plan then build

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 1. Switch to Plan mode
<Tab>

# 2. Describe the feature
When a user deletes a note, flag it as deleted in the DB.
Create a screen showing recently deleted notes with restore/permanent delete.

# 3. Iterate on the plan
Use this design as reference. [drag & drop image]

# 4. Switch back to Build mode
<Tab>

# 5. Implement
Sounds good! Go ahead and make the changes.

Custom commands

Define reusable prompts as commands in opencode.json or as markdown files in .opencode/commands/:

1
2
3
4
5
6
7
8
9

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage. Show failures and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build"
    }
  }
}

Then run with /test in the TUI. Commands support $ARGUMENTS, $1/$2 positional params, file references with @, and shell output with !`command`.

Tools available to the AI

File & code

Other

Permissions

Each tool can be set to allow, ask or deny, globally or per agent, with glob patterns for commands:

1
2
3
4
5
6
7

{
  "permission": {
    "edit": "ask",
    "bash": { "git push*": "ask", "rm -rf*": "deny", "*": "allow" },
    "webfetch": "allow"
  }
}

opencode --auto auto-approves everything not explicitly denied — sandboxes only.

Skills

Skills are folders with a SKILL.md (frontmatter name matching the folder, plus description), loaded on demand through the skill tool. OpenCode discovers them in .opencode/skills/, .agents/skills/ and .claude/skills/ (project, walking up to the git root) and in ~/.config/opencode/skills/, ~/.agents/skills/, ~/.claude/skills/ (global) — so Claude Code skills work as-is.

Non-interactive mode

Run a single prompt without the TUI:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ opencode run "Explain the use of context in Go"

# Raw JSON events
$ opencode run --format json "Explain context in Go"

# Attach files, pick model / agent / reasoning variant
$ opencode run -f src/main.py -m anthropic/claude-opus-5-5 --variant high "Review this file"

# Continue the last session
$ opencode run -c "Now add tests"

Other CLI commands

1
2
3
4
5
6
7
8
9

$ opencode serve               # Headless server (attach with `opencode attach <url>` or `run --attach`)
$ opencode web                 # Server + web UI
$ opencode pr 142              # Check out PR #142 and start opencode on it
$ opencode github install      # Set up the GitHub agent (runs in GitHub Actions)
$ opencode stats               # Token usage and cost
$ opencode models              # List available models
$ opencode mcp add             # Add an MCP server
$ opencode plugin <module>     # Install a plugin and update the config
$ opencode upgrade             # Self-update

LSP support

OpenCode ships built-in LSP servers (some auto-installed; disable downloads with OPENCODE_DISABLE_LSP_DOWNLOAD). LSP is disabled by default — once enabled, a server starts when a matching file is opened. Add or disable servers under lsp:

1
2
3
4
5
6
7
8
9

{
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"]
    },
    "typescript": { "disabled": true }
  }
}

MCP servers

OpenCode supports local (stdio) and remote (HTTP, with OAuth auto-detection) MCP servers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer {env:GH_PAT}"
      }
    },
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/projects"],
      "environment": { "MY_ENV_VAR": "value" },
      "enabled": true
    }
  }
}

Note that command is an array. Each server also accepts timeout (ms, default 5000); remote ones take an oauth object (or false).

Custom instructions

OpenCode reads project instructions from AGENTS.md (walking up from the current directory) and global ones from ~/.config/opencode/AGENTS.md. Generate the project file with /init.

For Claude Code compatibility it falls back to CLAUDE.md / ~/.claude/CLAUDE.md when no AGENTS.md exists (disable with OPENCODE_DISABLE_CLAUDE_CODE=1). Extra files (paths, globs or URLs) can be added with the instructions config key:

1

{ "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"] }

Copilot CLI vs OpenCode