OpenCode

Open-source multi-provider AI coding agent. The default backend for Broski.

Key Features

Multi-Provider Support

Connect to 75+ AI providers including Anthropic, OpenAI, Google, Amazon Bedrock, Azure, and more. Use your existing subscriptions (Claude Pro, ChatGPT Plus) or API keys.

Full MCP Support

First-class Model Context Protocol integration. Add custom tools, resources, and data sources through MCP servers.

Session Management

Create, fork, share, and summarize sessions. Generate public URLs to share conversations with teammates.

Open Source

Fully open-source with transparent code. Customize, extend, and contribute to the project.

OpenCode supports 75+ AI providers. See the OpenCode documentation for the full list.

Setup

Installation

bash

# Install script (recommended)
curl -fsSL https://opencode.ai/install | bash

# Or via bun
bun add -g opencode-ai

# Verify installation
opencode --version

Configure a Provider

Set your API key and select a default model:

bash

# Set API key (Anthropic example)
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Or OpenAI
export OPENAI_API_KEY=sk-your-key-here

# Set default model
opencode config set model "anthropic/claude-sonnet-4-20250514"

Configuration Files

OpenCode uses two configuration files — global (user-level) and project-level:

Global Config

~/.config/opencode/opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "dracula",
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-4-5-20250514",
  "autoupdate": true,
  
  // Tool permissions
  "permission": {
    "edit": "allow",
    "bash": { "*": "ask" },
    "webfetch": "allow"
  },
  
  // Enable/disable tools
  "tools": {
    "bash": true,
    "edit": true,
    "webfetch": true
  }
}

Project Config

.opencode/opencode.jsonc

{
  // Project-specific agent configuration
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4",
      "temperature": 0.3,
      "permission": {
        "bash": { 
          "npm *": "allow", 
          "git *": "allow",
          "rm -rf *": "deny"
        }
      }
    }
  },
  
  // Project MCP servers
  "mcp": {
    "database": {
      "type": "local",
      "command": ["node", "./scripts/mcp-db.js"]
    }
  }
}

Project config overrides global config. Use project config for repository-specific settings like allowed commands or custom MCP servers.

Built-in Tools

Tool	Description	Permission
`read`	Read file contents with optional line range	Safe
`write`	Create or overwrite files (requires prior read)	Approval
`edit`	Precise string replacement (oldString → newString)	Approval
`glob`	Find files matching pattern (e.g., */.ts)	Safe
`grep`	Regex search in file contents	Safe
`ls`	List directory contents	Safe
`bash`	Execute shell commands with timeout	Approval
`task`	Launch subagents for parallel work	Safe
`todowrite`	Create and manage task lists	Safe
`todoread`	Read current tasks	Safe
`webfetch`	Fetch web page contents	Configurable
`websearch`	Search the web for documentation	Configurable
`codesearch`	Search GitHub code examples	Safe
`skill`	Load specialized knowledge	Safe

MCP Server Configuration

Add MCP servers to extend OpenCode with custom tools and data sources:

.opencode/opencode.jsonc

{
  "mcp": {
    // Local MCP server (subprocess)
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem"],
      "environment": {
        "ALLOWED_PATHS": "/Users/me/projects"
      },
      "enabled": true
    },
    
    // Remote MCP server (HTTP/SSE)
    "github": {
      "type": "remote",
      "url": "https://mcp.github.com/sse",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

Session Management

Feature	Description
Create	Start new coding sessions in any project
Fork	Branch from any message point
Share	Generate public URLs to share sessions
Summarize	Compact long conversations to save context
Revert	Undo file changes to any message point

Troubleshooting

OpenCode Not Starting

Command not found

OpenCode is not installed or not in your PATH.

bash

# Check if installed
opencode --version

# If not found, reinstall:
bun add -g opencode-ai

# Or check your PATH:
echo $PATH

Port Conflict

Port 4096 in use

Another process is using OpenCode's default port.

bash

# Check what's using the port
# macOS/Linux:
lsof -i :4096
# Windows:
# netstat -ano | findstr :4096

# Use a different port
OPENCODE_PORT=4097 opencode

Provider Errors

Provider not configured

API key missing or invalid.

bash

# Verify API key is set
echo $ANTHROPIC_API_KEY

# Check OpenCode config
opencode config get

# Test API key directly
curl -H "x-api-key: $ANTHROPIC_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     https://api.anthropic.com/v1/messages \
     -d '{"model":"claude-3-sonnet-20240229","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

Health Check Failures

OpenCode health check failed

The bridge cannot connect to OpenCode.

bash

# Kill any stuck processes
pkill opencode

# Restart the bridge
broski

# Or check if OpenCode is running
ps aux | grep opencode

Claude Code

Anthropic's official agent

Codex

OpenAI's official agent

Backend Overview

Compare all backends

OpenCode

Key Features

Setup

Installation

Configure a Provider

Configuration Files

Global Config

Project Config

Built-in Tools

MCP Server Configuration

Session Management

Troubleshooting

OpenCode Not Starting

Port Conflict

Provider Errors

Health Check Failures

Next