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 or via @mention in messages.

Custom agents

Define custom agents in opencode.json or as markdown files in .opencode/agents/ (project) or ~/.config/opencode/agents/ (global):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "tools": { "write": false, "edit": false }
    }
  }
}

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-4-5",
  "small_model": "anthropic/claude-haiku-4-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

Non-interactive mode

Run a single prompt without the TUI:

1
2
3
4
5
6
7

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

# JSON output
$ opencode run "Explain context in Go" -f json

# Quiet (no spinner)
$ opencode run "Explain context in Go" -q

LSP support

OpenCode uses LSP for code intelligence. Install the server for your language, then configure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "lsp": {
    "python": { "command": "pylsp" },
    "go": { "command": "gopls" },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  }
}

MCP servers

OpenCode supports MCP via stdio, http, and sse transports:

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

{
  "mcp": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"]
    }
  }
}

Custom instructions

OpenCode reads project instructions from AGENTS.md at the project root. Generate it with /init.

You can also provide global instructions at ~/.config/opencode/agents/.

Copilot CLI vs OpenCode