OpenCode: the open-source agent for any model

OpenCode is an MIT-licensed coding agent (npm opencode-ai 1.18.32, repository anomalyco/opencode) that works with almost any model: hosted providers from the models.dev catalogue, OpenAI-compatible endpoints, and local servers such as Ollama. It matches Claude Code and Codex on agents, permissions, MCP, skills and headless runs. The trade-off is model choice versus one vendor’s tuned model-and-harness pairing.

Your security team says code for one client may not leave the building, finance asks why you pay for three agents, and a developer wants to try GLM-5.3 against the model you already use. Claude Code and Codex can point at a local server, but each is built around one vendor’s models. OpenCode is the harness built for the opposite case, and this page shows where that helps and where it costs you.

What this OpenCode reference gives you

A dated fact sheet, a first run, and one opencode.json that routes each task type to a different model.
Two verified routes to open-weight models, hosted and local, with their traps.
Capability and decision tables against Claude Code, Codex and Cursor.
A locked-down team configuration, three prompts, and a verification loop that does not depend on reading every diff.

What is OpenCode in September 2026?

OpenCode describes itself as “The open source AI coding agent” (repository description, read 2026-09-26). The facts that matter first:

Fact	Value (checked 2026-09-26)
Live repository	`anomalyco/opencode`, MIT, default branch `dev`
Not the live repository	`opencode-ai/opencode`, the original Go project, is archived. Kilo Code’s CLI is a fork of OpenCode (Kilo README)
Package	`opencode-ai` 1.18.32 on npm, published 2026-09-21
Surfaces	Terminal UI (`opencode`), headless runs (`opencode run`), a server (`opencode serve`) and web UI (`opencode web`), a desktop app in beta (macOS, Windows, Linux), and a GitHub agent (`opencode github`)
Built-in agents	Primary: build (all tools) and plan (file edits and bash set to `ask`). Subagents: general, explore and scout (the last two read-only)
Instruction file	`AGENTS.md`; falls back to `CLAUDE.md` when no `AGENTS.md` exists
Extension points	MCP servers, Agent Skills, custom agents, JavaScript or TypeScript plugins with event hooks, custom tools, LSP servers

Popularity, dated. 210,085 GitHub stars (GitHub, anomalyco/opencode, 2026-09-26), the most-starred agent outside the big three on the landscape page. Stars measure attention, not fitness for your codebase.

How do you install OpenCode and run it on a repository?

The README lists more than ten installers. Use one of the four below, then work inside the repository you want the agent to change.

Install the CLI in your terminal:

curl -fsSL https://opencode.ai/install | bash
# or one of:
npm i -g opencode-ai@latest
brew install anomalyco/tap/opencode
mise use -g opencode

Start it in the repository root with opencode, then run /connect and pick a provider. Credentials are stored in ~/.local/share/opencode/auth.json, outside the repository. opencode auth login does the same from the shell.
Run /models to pick a model. From the shell, opencode models anthropic lists one provider’s models in provider/model form, and opencode models --refresh reloads the catalogue from models.dev.
Run /init. It scans the repository, may ask a few questions, and writes or updates AGENTS.md. If the repository already has an AGENTS.md for Codex, OpenCode reads it as is.
Press Tab to switch to the plan agent before your first task, so the agent proposes changes and asks before it edits a file or runs a command. Switch back to build when you accept the plan.

Two defaults surprise people who arrive from Claude Code. First, most permissions default to allow in the build agent; only doom_loop and external_directory default to ask, and .env files are denied to read (permissions docs, 2026-09-26). Second, OpenCode also loads ~/.claude/CLAUDE.md as a global fallback. Set OPENCODE_DISABLE_CLAUDE_CODE=1 if your personal Claude Code rules should not leak into OpenCode sessions.

How does OpenCode choose and route models?

Every model is addressed as provider/model, with IDs from the models.dev catalogue that OpenCode’s team also maintains. With no --model flag, OpenCode resolves the model in this order: the -m flag, the model key in config, the last model you used, then an internal priority. There is no single vendor default, so set one explicitly.

Keys apply at three levels: model for the primary agents, small_model for light internal work, and model inside each agent definition. That is enough to route work by job:

{
  "$schema": "https://opencode.ai/config.json",
  // Build and plan: your strongest model.
  "model": "anthropic/claude-opus-5-5",
  // Light internal tasks: a cheap, fast model.
  "small_model": "anthropic/claude-haiku-4-5",
  "agent": {
    // A reviewer from a different vendor catches what the author's model misses.
    "review": {
      "description": "Reviews the working-tree diff against AGENTS.md and the tests. Never edits.",
      "mode": "subagent",
      "model": "openai/gpt-6-sol",
      "permission": { "edit": "deny", "bash": { "*": "deny", "git diff*": "allow", "git status*": "allow", "npm test*": "allow", "npm run lint*": "allow" } }
    },
    // An open-weight model for bulk, low-risk work such as test scaffolding.
    "bulk": {
      "description": "Mechanical edits and test scaffolding on well-specified tasks.",
      "mode": "subagent",
      "model": "zai/glm-5.3"
    }
  }
}

The four IDs above exist in the models.dev catalogue on 2026-09-26. Run opencode models after connecting providers to confirm the exact IDs your account can reach, because OpenCode’s own documentation examples still show older model IDs. Prices and context windows for every model named here are on the models hub; the site does not repeat them.

Choose models with the rule the rest of this site follows, adapted to a harness with no default of its own: start on each vendor’s default model (Claude Opus 5.5 for Anthropic, GPT-6 Astra for OpenAI), tune reasoning effort before you switch model (opencode run --variant passes a provider-specific effort level), and switch only when your own evals say so.

Which subscriptions you can bring matters for cost:

You pay for	Works in OpenCode?	How
ChatGPT Plus or Pro	Yes, “with zero setup”	`/connect` → OpenAI → ChatGPT Plus/Pro
GitHub Copilot	Yes; some models need Copilot Pro+	`/connect` → GitHub Copilot, device login
GitLab Duo	Yes, experimental; needs GitLab Premium or Ultimate with Duo Agent Platform	`/connect`
Claude Pro or Max	No. “Anthropic explicitly prohibits this”; OpenCode stopped bundling the workaround plugins in 1.3.0	Use an Anthropic API key
Any API key	Yes, 75+ providers per the docs	`/connect` → Manually enter API Key

How do you run open-weight models in OpenCode?

There are two routes, and they answer different questions. A hosted provider answers “is this model good enough for our work?” cheaply. A local server answers “can this run where our code is allowed to be?”

Hosted open-weight models. Connect the provider and pick the model. For GLM-5.3 on Z.AI, run /connect, search for Z.AI, select Z.AI Coding Plan if you subscribe to the GLM Coding Plan, paste the key, then /models. OpenRouter, DeepSeek, Together AI, Groq and Hugging Face are also first-class providers. OpenCode’s team offers two model lists of its own: Zen (“tested and verified to work well with OpenCode”) and Go (“a low cost subscription plan” for “popular open coding models”). Both are optional.

Self-hosted models. Any OpenAI-compatible server works through the @ai-sdk/openai-compatible adapter. Ollama is one command, ollama launch opencode, which applies inline configuration without overwriting yours. The manual equivalent from Ollama’s OpenCode guide:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "qwen3.5": { "name": "qwen3.5" } }
    }
  }
}

qwen3.5 is the tag Ollama’s guide uses; replace it with the tag you pulled. LM Studio uses http://127.0.0.1:1234/v1 and llama.cpp’s server (llama serve, formerly llama-server) listens on http://127.0.0.1:8080/v1 by default.

Three requirements decide whether a local model works at all:

Context of 64K tokens or more. Ollama’s OpenCode page requires “a context length of 64k or higher”. Ollama’s default context depends on VRAM and is 4K below 24 GiB, which silently truncates the agent’s system prompt. Start the server with OLLAMA_CONTEXT_LENGTH=64000 ollama serve and confirm the CONTEXT column in ollama ps.
Tool calling. The agent is useless without it. OpenCode’s docs: “If tool calls aren’t working, try increasing num_ctx in Ollama.”
Local tags only. Ollama tags that end in :cloud run on Ollama’s cloud, so code leaves the machine. Pin local tags when the reason you are here is data residency.

Check the licence before a model enters production: GLM-5.3’s repository code is Apache-2.0 but its weights licence is on the model card, Kimi K3 ships under a custom licence that is not OSI open source, and Mistral Medium 3.5 uses a Modified MIT licence (facts as of 2026-09-26). The full comparison of GLM, Qwen, Kimi, DeepSeek and Mistral models for coding agents is on open-weight and self-hosted models.

What the public evidence says about the quality gap. GLM-5.3 is the only open-weights entry on the official Terminal-Bench 4.0 board: 41.8% ± 3.2, run through Claude Code, against 37.3% ± 3.8 for GPT-5.6 Sol in Codex; the intervals overlap, so the board does not separate them (harbor-framework submissions, checked 2026-09-26). No OpenCode run is on that board (checked 2026-09-26), so how OpenCode’s harness changes any model’s score is unmeasured. Your own closed issues are the only benchmark that settles it.

Where does OpenCode match Claude Code, Codex and Cursor, and where does it not?

OpenCode covers the harness features a team standardises on. It differs in who owns the model, the cloud runtime and the support contract. Cursor cells come from Cursor’s docs as checked on 2026-08-28; cells marked not verified could not be re-checked on 2026-09-26.

Capability	OpenCode 1.18.32	Claude Code 2.1.283	Codex 0.157.1	Cursor
Models	Any models.dev provider, any OpenAI-compatible endpoint	Anthropic models; other models through an Anthropic-compatible gateway	OpenAI models; local through `--oss`	Not verified
Instruction file	`AGENTS.md`, `CLAUDE.md` fallback	`CLAUDE.md`; `AGENTS.md` when no `CLAUDE.md` (from v2.1.277, `latest` channel)	`AGENTS.md`	Rules
Read-only planning	plan agent (edits and bash ask)	Plan mode	`/plan`	Plan Mode
Subagents	general, explore, scout, custom (`mode: subagent`)	Explore, Plan, general-purpose, custom	`/subagents`	Subagents
Permission rules	Per tool, glob patterns, last match wins	Allow and deny rules, permission modes	Sandbox modes, `.rules`	Not verified
Hooks	Plugin events (`tool.execute.before`, `session.idle`, `file.edited`, …) in JS or TS	33 hook events	12 hook events	Hooks (JSON over stdio)
MCP and skills	Both; reads `.claude/skills/` and `.agents/skills/`	Both	Both	Both
Headless and CI	`opencode run --format json`, `opencode serve`, GitHub agent	`claude -p`, GitHub Action	`codex exec`, `codex review`	CLI `-p` print mode, GitHub Actions, Cloud Agents
Vendor cloud agent	None in the docs checked on 2026-09-26; the GitHub agent runs on your Actions runners	Yes	Yes	Yes
Cost reporting	`opencode stats`	`/usage`	`/usage`	Not verified

What you give up by choosing OpenCode:

The tuned pairing. Every Anthropic and OpenAI entry on the official Terminal-Bench 4.0 board runs the vendor’s model in the vendor’s own harness. With OpenCode, the model-and-harness combination you run is one nobody has benchmarked publicly.
Safe-by-default permissions. The build agent allows most tools out of the box. You write the guardrails.
One accountable vendor. A bad result could be the model, the provider adapter or the harness. Budget time for that triage.
A stable surface. OpenCode ships often (1.18.32 was published 2026-09-21), and its own docs still use older model IDs in examples. Pin the version your team tested.

To try the same open-weight model in the agent you already use before deciding, the routes differ per tool:

Claude Code speaks the Anthropic Messages API, which Ollama implements. Ollama’s Claude Code guide:

ollama launch claude
# or manually:
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3.5

With a non-Anthropic base URL, Remote Control and /voice are unavailable. Check /status to confirm the gateway is the one in use.

Codex has a built-in switch for Ollama and LM Studio (codex --help, 0.157.1):

codex --oss --local-provider ollama -m qwen3.5

ollama launch codex sets up a dedicated profile instead.

Cursor’s support for local or open-weight models could not be verified on 2026-09-26. Check Cursor’s model settings documentation before you plan around it, or run the comparison in OpenCode, which shares your repository’s AGENTS.md and skills.

How do you lock OpenCode down for a team?

Commit one opencode.json to the repository so every developer and every CI run starts from the same rules. Project config merges over the user’s global config key by key, and an organisation can publish defaults at .well-known/opencode.

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled",
  "autoupdate": false,
  "instructions": ["CONTRIBUTING.md"],
  "permission": {
    "edit": "ask",
    "external_directory": "deny",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "npm test*": "allow",
      "npm run lint*": "allow",
      "git push*": "deny",
      "rm *": "deny"
    }
  }
}

Rules are matched by pattern and the last matching rule wins, so put the catch-all "*" first and the exceptions after it. share: "disabled" matters because a shared session uploads the full conversation to OpenCode’s servers under an opncd.ai/s/<id> link. autoupdate: false keeps everyone on the version you tested; upgrade deliberately with opencode upgrade. MCP servers go under mcp in the same file, and the docs warn that some, such as the GitHub MCP server, “can easily exceed the context limit”. Enable only the servers a task needs; see MCP servers and skills.

For the broader model of approvals, sandboxes and network limits, see permissions and sandboxing.

Copy-paste prompts for OpenCode

Read CLAUDE.md, .claude/settings.json, .claude/agents/ and .mcp.json in this repository.
Produce two files and nothing else:
1. AGENTS.md: the project rules from CLAUDE.md, rewritten tool-neutrally (no Claude-specific
   commands or slash commands). Keep every build, test and lint command exactly as written.
2. opencode.json: MCP servers from .mcp.json under "mcp" (type "local" with a command array,
   or type "remote" with a url; secrets as {env:VAR}, never literal values), and a "permission"
   block that mirrors the allow and deny rules in .claude/settings.json. Put "*": "ask" first in
   each pattern map, because the last matching rule wins. Set "share": "disabled".
Then list every Claude Code feature you could not map (hooks, output styles, plugins) with the
OpenCode equivalent if one exists, or "none".

@review Review the uncommitted changes in this repository (git diff HEAD). You may not edit files.
1. Run the test and lint commands listed in AGENTS.md and report pass or fail for each.
2. For each changed function, name the test that exercises it, or write "UNTESTED".
3. Flag any change that touches authentication, payments, migrations or public API signatures.
4. Flag any new dependency and check that it exists in the lockfile.
Answer as a table: file, finding, severity (block / fix before merge / note), evidence.
End with one line: MERGEABLE or NOT MERGEABLE, and the reason.

You are reproducing a fix that was already merged, to compare models fairly.
Task: <paste the text of closed issue #NNN here, without the linked pull request>.
Rules: change only the files needed; run the full test suite before you finish; do not edit
or delete existing tests. When done, print: files changed, tests added, the final test
command and its exit code, and anything you were unsure about.

Run it headless once per model, each in a fresh checkout of the commit before the fix: opencode run -m anthropic/claude-opus-5-5 --format json "$(cat task.txt)" > opus.jsonl, then again with -m zai/glm-5.3. Score both with the bake-off protocol.

How do you verify what OpenCode produces without reading every line?

Model freedom adds a variable, so the verification loop has to be stronger than with a single-vendor tool, not weaker.

Deterministic gates own merge. Tests, type checks and lint run in CI on every change, whichever model wrote it. The agent’s claim that tests pass is not evidence; the CI log is.
A cross-model reviewer. The review subagent above runs on a different vendor’s model with edits and most shell commands denied. Correlated blind spots are the risk when the same model writes and reviews.
A per-model eval before a model gets a new job. Run 10 to 20 of your own closed issues through each candidate model with the third prompt and score them with the landscape page’s protocol. Promote a model (for example, to the bulk agent) only on that evidence, and rerun the set when a model or OpenCode version changes.
An evidence bundle on every pull request. Record the model ID, OpenCode version, test results and reviewer verdict in the pull request, as described in the evidence bundle. Without the model ID, you cannot trace a regression to a model swap.
Cost you can see. opencode stats --models reports token use and cost per model (filter with --days and --project), so a cheap model that needs three attempts shows up as expensive.

The tech lead owns the model-to-agent routing in opencode.json, and changes to it go through review like code. The CI gates, not the reviewer’s reading, decide whether a change merges.

For comment-driven runs, opencode github install sets up a GitHub Actions workflow that responds to /opencode or /oc in issue and pull request comments. The agent runs only for commenters with write or admin access (assertPermissions in github/index.ts of anomalyco/opencode, checked in 1.18.32), but on a pull request it checks out the PR branch, including branches from forks, and loads that branch’s opencode.json, plugins and AGENTS.md while your API key is in the environment. So do not trigger it on pull requests from forks, and review any change to opencode.json or .opencode/ before you comment /oc. As defence in depth, add an author check to the job condition and keep persist-credentials: false from the generated file:

if: |
  (contains(github.event.comment.body, '/oc') || contains(github.event.comment.body, '/opencode')) &&
  contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)

See headless agents in CI for secret handling across agents.

What breaks when teams adopt OpenCode?

Tool calls fail or the agent ignores its instructions on a local model. The usual cause is Ollama’s VRAM-based default context of 4K, which truncates the system prompt. Recovery: restart with OLLAMA_CONTEXT_LENGTH=64000, confirm with ollama ps, and if tool calls still fail, switch to a model whose card lists tool calling.

Code leaves the machine on an “air-gapped” setup. A model tag ending in :cloud, a shared session, or a hosted small_model sends data out while the main model is local. Recovery: pin local tags, set share: "disabled", point small_model at the local provider too, and restrict the enabled providers with enabled_providers.

The build agent runs a destructive command nobody approved. Most permissions default to allow. Recovery: commit the team baseline above, and review git reflog and the session export (opencode export --sanitize) to see what ran.

A headless run in CI hangs or does too much. The docs (checked 2026-09-26, 1.18.32) do not say what opencode run does with an ask rule and no human, and --auto approves everything not explicitly denied. Recovery: in CI, write explicit allow and deny rules for every tool the job needs, use --auto only inside a disposable, network-restricted sandbox, and never on a runner that holds production secrets.

Claude Pro or Max login stops working. The subscription table above explains why. Recovery: use an Anthropic API key, or connect ChatGPT Plus or Pro, or GitHub Copilot.

A config example fails with “model not found”. OpenCode’s documentation examples use older model IDs, and the catalogue moves. Recovery: run opencode models --refresh, then copy the ID from opencode models <provider>.

Personal Claude Code rules appear in OpenCode sessions. OpenCode reads ~/.claude/CLAUDE.md and ~/.claude/skills/ as fallbacks. Recovery: set OPENCODE_DISABLE_CLAUDE_CODE=1, or move the shared rules into AGENTS.md.

The open-weight model looked fine in a demo and fails on real work. A single impressive session is not an eval. Recovery: run the closed-issue comparison above on at least 10 issues, and keep the model on low-risk agents until it matches your current default on your own gates.

When should you choose OpenCode?

Your situation	Recommendation
Code may not leave your network, or a client contract rules out a vendor’s harness	OpenCode with a local server, after the per-model eval; see gateways and local models
You already pay for ChatGPT Plus or Pro, or GitHub Copilot, and want one terminal agent across models	OpenCode with that subscription connected; keep your current agent for comparison
You want to route cheap, well-specified work to an open-weight model	OpenCode’s per-agent `model`, promoted only on eval evidence
Your team is on Claude Pro or Max seats	Stay on Claude Code; OpenCode needs separate API billing for Anthropic models
You want vendor-managed cloud agents and one support contract	Stay on Claude Code, Codex or Cursor
You want to avoid lock-in whichever agent you pick	Keep rules in `AGENTS.md` (read by OpenCode and Codex, and by Claude Code when there is no `CLAUDE.md`) and workflows as Agent Skills; see lock-in and portability

Where to go next with OpenCode

Open-weight and self-hosted models GLM, Qwen, Kimi, DeepSeek and Mistral models for air-gapped work, cost floors and data rules, and how to measure the gap on your evals.

The coding-agent landscape beyond the big three Where OpenCode sits among Copilot, Gemini CLI, Kiro and the rest, and the bake-off protocol to compare them.

Models hub Current model names, prices, context windows and defaults in one place.

Gateways and local models Ollama, LM Studio, llama.cpp, LiteLLM and routers for any agent, with the context and data traps.

Frequently asked questions

What is OpenCode?

OpenCode is an MIT-licensed coding agent for the terminal, with a headless mode, a server and a desktop app in beta. The live project is anomalyco/opencode (npm opencode-ai 1.18.32 on 26 September 2026); the older Go repository opencode-ai/opencode is archived.

Which models can OpenCode use?

Any provider in the models.dev catalogue (Anthropic, OpenAI, GitHub Copilot, Amazon Bedrock, OpenRouter, Z.AI, DeepSeek and more), any OpenAI-compatible endpoint, and local servers such as Ollama, LM Studio and llama.cpp. Models are addressed as provider/model.

Can I use my Claude Pro or Max subscription in OpenCode?

No. OpenCode's own provider docs say Anthropic explicitly prohibits it, and OpenCode stopped bundling the plugins that did it in 1.3.0. Use an Anthropic API key instead. ChatGPT Plus or Pro and GitHub Copilot subscriptions work; GitLab Duo support is experimental and needs a GitLab Premium or Ultimate plan with the Duo Agent Platform.

Should a team replace Claude Code or Codex with OpenCode?

Only when model choice is the requirement: self-hosted or open-weight models, one harness across several vendors, or a data rule that excludes a vendor's harness. Otherwise the vendor's own agent, tuned for its own models, is the lower-risk default.