OpenCode from Zero to Production.

Install, configure providers, plug in MCP — plus an honest comparison with Claude Code, Codex CLI, and Cursor CLI.

TL;DR
  • Pick OpenCode when: you want provider freedom, you already have API keys, or you want to mix local + cloud models.
  • Pick Claude Code when: you want the most polished Anthropic experience with sub-agents and skills built-in.
  • Pick Cursor CLI when: you live in Cursor and want CLI-from-the-editor parity.
  • Pick Codex CLI when: you trust OpenAI's autonomous long-run loops for batch refactors.
CH 01

Install in 60 seconds.

OpenCode ships as a single binary. Three ways to get it:

$ install OpenCode 
# Homebrew (macOS / Linux)
brew install opencode-ai/tap/opencode

# curl bootstrap (Linux / WSL)
curl -fsSL https://opencode.ai/install | sh

# npm (works everywhere)
npm install -g opencode-ai

# Verify
opencode --version

First run drops a config at ~/.opencode/opencode.json. You'll edit that to set your provider, model, and tool permissions. Defaults are sensible but bland; the next chapter is where it gets useful.

CH 02

Pick a provider (or three).

OpenCode's killer feature is swapping providers per task. You can default to Anthropic Sonnet for the agent loop, route long-context summaries to Gemini, and use a local Llama for offline drafts — all from one config.

~/.opencode/opencode.json 
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "{env:ANTHROPIC_API_KEY}",
      "models": ["claude-sonnet-4-6", "claude-opus-4-7"]
    },
    "google": {
      "apiKey": "{env:GOOGLE_API_KEY}",
      "models": ["gemini-3-1-pro"]
    },
    "ollama": {
      "baseURL": "http://localhost:11434",
      "models": ["llama3.3:70b"]
    }
  },
  "defaultModel": "claude-sonnet-4-6",
  "theme": "opencode-dark"
}

Switch on the fly with /model inside a session. Cost-conscious workflow: default Sonnet, /model opus when the task is hard, /model llama when you're offline on a flight.

Pitfall · Putting raw keys in the config

The {env:NAME} interpolation is there for a reason. If you write "apiKey": "sk-ant-..." in the file, the file and any backup of your home directory contains a live key. Use env vars; store them in ~/.config/opencode/env if you don't want them in your shell rc.

CH 03

Project config: rules, skills, AGENTS.md.

OpenCode reads four conventional things from your repo, in order:

  1. AGENTS.md at the repo root — orientation, conventions, file map.
  2. .opencode/rules/*.md — always-on rules (think: lint rules for prose).
  3. .opencode/skills/*.md — on-demand capabilities the agent invokes itself.
  4. .opencode/agents/*.json — named modes with their own model + tool policy.

The skills directory is portable — the same SKILL.md files we publish at /skills/ work as-is when dropped into .opencode/skills/. Same pattern as Cursor and Claude Code.

.opencode/agents/review.json 
{
  "name": "review",
  "description": "Read-only audit mode for catching bugs before deploy",
  "model": "claude-opus-4-7",
  "tools": {
    "read": true,
    "grep": true,
    "write": false,
    "shell": false
  },
  "system": "You are a senior reviewer. Identify bugs, security holes, and accessibility issues. Suggest fixes but never edit files."
}
CH 04

MCP integrations.

OpenCode speaks the same MCP protocol as Claude Code, Cursor, and Codex CLI — anything that's an MCP server runs here too. Add servers in the config:

~/.opencode/opencode.json (mcp section) 
{
  "mcp": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "postgres": {
      "command": "uvx",
      "args": ["mcp-server-postgres"],
      "env": { "POSTGRES_URL": "{env:DATABASE_URL}" }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" }
    }
  }
}

Same MCP-shopping rules apply as in the Cursor guide: every server eats tool-call budget. Two well-used MCPs > ten installed-and-forgotten.

CH 05

OpenCode vs the alternatives.

The honest comparison. All four CLIs do the same fundamental thing — agent loop in a terminal — but each has a flavor.

Dimension OpenCode Claude Code Codex CLI Cursor CLI
Provider freedom Any Anthropic OpenAI Bundle
Billing BYO API keys Subscription or API API only Subscription
Open source Yes No CLI only No
Sub-agents Yes (basic) Polished Yes Yes (Cloud)
MCP Yes Yes Yes Yes
Editor pairing Standalone Standalone Standalone Cursor
Local-model support First-class No No Partial
Long autonomous runs Solid Excellent Excellent Excellent (Cloud)
DEMO · INTERACTIVE

Live: which CLI fits you?

Six questions. Weighted scoring. Answer honestly and you'll get a recommendation matched to how you actually work. No emails, no signup, no tracking — this runs entirely in your browser.

Which CLI fits you? 6 questions · 30 seconds
PITFALLS

Common pitfalls.

"Free" overstated

OpenCode the binary is free. The model bills are very much not. Hook into the cost guide's calculator before you commit to a provider plan.

Configuring six providers, using two

OpenCode makes it easy to add five providers. Most people use one or two. Empty provider entries don't cost tokens but they do clutter the model picker and slow down switching. Audit quarterly.

Local model on the wrong task

Llama 3.3 70B on a laptop is great for drafting and chat — terrible at tool-call-heavy agent loops. Use local for offline summaries and brainstorms, not for "build me a Next.js feature."

What to read next.