Which OpenCode do you mean?
Three different things answer to the name, and picking the wrong one costs you an afternoon. Sort this out first; everything else on this page depends on it.
| If you land on | What it actually is | What to do |
|---|---|---|
github.com/sst/opencode | The original home. It now issues a permanent redirect to github.com/anomalyco/opencode, and the sst organisation bio reads “We’ve moved to https://github.com/anomalyco”. | Follow the redirect. The publisher is Anomaly; the documentation footer credits it. Nothing about the project itself changed with the move. |
github.com/opencode-ai/opencode | A different project entirely, in Go, now archived. Its README opens “Archived: Project has Moved” and continues that the project “has continued under the name Crush, developed by the original author and the Charm team”. | You want Crush, at charmbracelet/crush. Anything written about “opencode” before that split may describe this one and not Anomaly’s. |
The npm package opencode-ai | Confusingly, the npm package name of the surviving OpenCode v1 — the same string as the archived project’s GitHub organisation. | npm install -g opencode-ai installs OpenCode v1 and is correct. The collision is real and the package is not the archived project. |
The npm package @opencode/cli | OpenCode v2 — a separate distribution with its own installer, Homebrew formula and documentation site. | Read the v1-versus-v2 section below before installing it. It replaces v1 rather than sitting beside it. |
The surviving project describes itself simply: “OpenCode is an open source AI coding agent. It’s available as a terminal-based interface, desktop app, or IDE extension.” It is MIT licensed, and the official documentation lives at opencode.ai/docs for v1 and opencode.ai/v2/docs for v2.
v1 and v2 are separate distributions
curl -fsSL https://opencode.ai/install | bash
brew install anomalyco/tap/opencode
npm install -g opencode-ai
# also available
pnpm install -g opencode-ai
sudo pacman -S opencode
choco install opencode
scoop install opencode
docker run -it --rm ghcr.io/anomalyco/opencodecurl -fsSL https://opencode.ai/v2/install | bash
brew install anomalyco/tap/opencode-v2
npm install -g @opencode/cli
# also available
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli
docker run -it --rm ghcr.io/anomalyco/opencode:2.0.0The documentation is explicit that the Homebrew tap is the one to prefer: “We recommend using the OpenCode tap for the most up to date releases. The official brew install opencode formula is maintained by the Homebrew team and is updated less frequently.”
| What changed in v2 | Detail |
|---|---|
| Plugin API | Plugins use a new plugin API. Existing v1 plugins need porting. |
| Server contract | The server API and clients have new contracts. Anything integrating over the v1 server API needs review. |
| Shared background server | By default, OpenCode discovers or starts one shared background server per user account, and every local client connects to it. That server owns sessions, configuration, integrations, permissions and tool execution. Override with opencode --standalone or opencode --server http://localhost:4096. |
| Terminal client config | Layered tui.json(c) files become one global cli.json, migrated automatically. |
| Instruction files | The CLAUDE.md fallback is removed. See below. |
| What survives | Supported server config fields, agent definitions, command definitions, skills and other files under .opencode/ continue to work unchanged. |
Platform support differs between the lines too. v1 recommends WSL on Windows in as many words: “For the best experience on Windows, we recommend using Windows Subsystem for Linux (WSL). It provides better performance and full compatibility with OpenCode’s features.” v2 ships standalone binaries for macOS on Apple silicon and Intel, Windows on ARM64 and x64, and Linux against both glibc and musl — and states flatly that Windows package managers are not supported. v2 also adds a desktop app and a web interface through opencode pair.
Auth: three different ways in
- Bring a provider key. Each provider declares the environment variables it reads, such as
OPENROUTER_API_KEY, andopencode auth loginwalks you through it with--providerand--methodflags. - Connect a subscription from inside the interface: “Run the
/connectcommand in the TUI, select opencode, and head to opencode.ai/auth.” - Run against the hosted gateway, either pay-as-you-go or on the Go subscription.
If you run the headless server, it takes its own credentials: OPENCODE_SERVER_PASSWORD and OPENCODE_SERVER_USERNAME, the latter defaulting to opencode. Treat that as a service credential rather than an afterthought — the v2 shared background server owns permissions and tool execution for every local client.
What it costs: the CLI is free, the gateway is not
The CLI itself is free and MIT licensed, and you never have to pay Anomaly anything to use it. Two optional paid paths exist on top. OpenCode Go is described as “a low cost $10/month subscription that gives you reliable access to popular open coding models”, and the documentation adds that “it’s completely optional and you don’t need it to use OpenCode” and that it “is designed primarily for international users and provides stable global access.” Only one member per workspace can subscribe to Go.
| Window | Go plan limit |
|---|---|
| Rolling 5-hour | $12 |
| Weekly | $30 |
| Monthly | $60 |
The other path is the gateway. OpenCode Zen is “a list of tested and verified models provided by the OpenCode team… an AI gateway that gives you access to these models”, billed pay-as-you-go per token with no tiers, and it rotates a set of models that are temporarily free. In v2 that is folded into OpenCode Console, “an optional service that provides additional benefits to using OpenCode particularly as a team”, covering inference, a gateway for your own provider keys, usage tracking and budget controls, team policies and web search. There is no /pricing page to link; Go and Console are documented separately.
Models: you declare the context window
OpenCode does not have a context window. Its models do, and you assert it. Models carry a limit object with context and output values, and for a model it does not recognise the documentation is careful about what it is doing: it assumes “a 200,000-token context limit and 32,000-token output limit” and calls those “fallback assumptions, not detected capabilities.”
Local runtimes are the exception, because they can be asked. Ollama and LM Studio inventories are discovered automatically — OpenCode “refreshes the inventory in the background and reads context, vision, and tool-use capabilities from Ollama”, and takes max_model_len from LM Studio. Models are referenced as provider/model, such as anthropic/claude-3-5-sonnet, selected with --model or -m, and listed with opencode models [provider].
That is the opposite end of the spectrum from Cursor CLI, which brokers every model itself and will not take your provider key at all. If portability across vendors matters more than a managed catalogue, this is the reason to pick OpenCode; the six-agent comparison puts that axis next to everything else.
Agents, subagents, and plugins as the hook surface
Two primary agents ship by default: Build, which is the default, and Plan, which is read-only. Three subagents ship alongside them — General, Explore and Scout — plus hidden system agents for compaction, titling and summaries. Custom agents live in ~/.config/opencode/agents/ and .opencode/agents/, as Markdown files or as entries in opencode.json.
Delegation is a tool rather than a flag. The documentation describes it directly: “subagent starts a child session with a configured subagent. Supply the agent ID, a short description, and a complete prompt.” It accepts background: true and returns a sessionID, and only subagent-mode agents can be used, with a default nesting depth of one.
Extension works through plugins, not through a shell-hook configuration block. Plugins “add tools, hooks, integrations, commands, agents, and other behavior”, live in .opencode/plugins/ and ~/.config/opencode/plugins/, and subscribe to an event bus that includes tool execution before and after, permission asked and replied, session created, idle, status and compacted, file edited, message updated, command executed, todo updated and terminal and language-server events.
Worktrees in v2, and the sandbox that is not documented
v2 makes worktrees native configuration rather than a flag. A worktree object sets the directory, for example {"worktree": {"directory": "../worktrees"}}, and the default location is worktree/<first-six-project-ID-characters> under the server data directory. Strategy is pluggable: “Git is the built-in default. A plugin that registers a strategy automatically becomes the default in that plugin runtime.” There is even a session-move tool, so you can tell the agent to rename a session and move it to a new worktree. v1 has no documented equivalent.
Isolation is the gap. The string “sandbox” appears in none of the 23 v1 and v2 documentation pages we checked, and no page denies one either — so this site shows a dash rather than a no. What is documented is a permission and policy layer, with a warning that leaves little room for doubt about what it is not: “shell runs with the host user’s filesystem, process, and network authority. Directory inference from command text is best effort, so prefer a narrow shell allowlist.”
Take that at face value when you decide what to hand over. A narrow shell allowlist plus a disposable worktree is a real boundary; it is just a different kind of boundary from a kernel sandbox. The sandbox and permission guide sets out how to match authority to consequence, and it applies here even though the mechanism differs.
Sessions, headless runs and server mode
opencode run "fix the failing parser test"
opencode run -c # continue the last session
opencode run -s <sessionID> # continue a specific session
opencode run -s <sessionID> --fork # branch instead of continuing
opencode session list
opencode session delete <sessionID>
opencode serve --port 4096 --hostname 127.0.0.1
opencode debug paths dbSessions persist in SQLite. opencode debug paths db prints the location, and OPENCODE_DB overrides it. v2 adds opencode mini for a minimal interactive interface, the opencode debug paths family for every other directory it uses, and opencode uninstall with --dry-run, --keep-config and --keep-data flags. The flag reference quoted above comes from the v1 documentation: v2 publishes no parameters table and tells you to run opencode mini --help instead.
AGENTS.md — and in v2, only AGENTS.md
The loading order is worth knowing because it is unusual. Global instructions at ~/.config/opencode/AGENTS.md load first, then project files nearest-first — and they load lazily as the agent explores: “Reading a file or listing a directory loads any AGENTS.md files between that target and the workspace.” A monorepo can therefore carry packages/AGENTS.md and packages/web/AGENTS.md, and only the relevant ones enter the context. Opt out of project configuration entirely with OPENCODE_DISABLE_PROJECT_CONFIG=1.
JSON configuration is read from ~/.config/opencode/opencode.json(c), <project>/opencode.json(c) and <project>/.opencode/opencode.json(c) by both lines, against the schema at https://opencode.ai/config.json. Among the six agents in this cluster, Kimi Code CLI is the only other one that reads AGENTS.md and nothing else; Grok Build sits at the opposite extreme and reads every Claude-shaped file as well.
Where CmdBrief fits
CmdBrief supervises Claude Code, Codex, Grok CLI, Kimi CLI, OpenCode and Cursor CLI in one Mac workspace, with per-product workspaces, working, needs-input and done states, diff review and an integrated terminal. For OpenCode it lists sessions with opencode session list --format json, reads Go-plan usage through the hosted gateway using the key /connect writes into auth.json, and detects agent state by process and screen because there is no hook API to attach to.
One caveat while v2 settles: that integration is built against the v1 shape — the session list contract and the local store beneath it. v2 introduces a new server API contract and a shared background server that owns sessions, so if you are running the v2 line, expect the session list and the Go meter to be the first things to need attention.
OpenCode is also the cheapest way into this category, which makes it a common second agent rather than a replacement for a first. Claude Code vs Codex covers the two most people already pay for, running two agents in parallel is the worktree pattern that keeps them out of each other’s way, and the tool comparisons cover the workspaces you would run them in.
Questions
Is OpenCode still maintained by sst?
No. github.com/sst/opencode permanently redirects to github.com/anomalyco/opencode, and the sst organisation bio states that the team has moved to Anomaly. The project is the same MIT-licensed codebase under a new publisher; no statement explains why the move happened, so that is all this page will claim.
Should I install OpenCode v1 or v2?
Both lines ship actively — v1 reached 1.18.32 on 21 September 2026 and v2 reached 2.0.13 on 22 September. They are separate distributions with different npm packages, installers and Homebrew formulae, and they cannot be installed side by side by default: the v2 installer replaces the v1 binary, so remove a package-managed v1 first. v2 brings a new plugin API, a new server contract, a shared background server, one global cli.json, native worktrees, and no CLAUDE.md fallback. Anomaly has not published an end-of-life date for v1.
Is OpenCode the same thing as Crush?
No, though the confusion is well earned. opencode-ai/opencode was a different Go project that was archived and continued under the name Crush by its original author and the Charm team. Anomaly’s OpenCode is a separate TypeScript project — and, awkwardly, opencode-ai is also the npm package name of Anomaly’s v1.
Is OpenCode free?
The CLI is free and MIT-licensed, and you can run it entirely on your own provider keys or against local Ollama and LM Studio models. Two optional paid paths exist: the Go subscription at $10 a month, metered in dollars of inference at $12 per 5-hour window, $30 weekly and $60 monthly; and the pay-as-you-go gateway, which rotates a set of temporarily free models.
Does OpenCode sandbox shell commands?
No sandbox is documented on any of the 23 v1 and v2 pages we checked, and none of them denies one either, so this page shows a dash. What is documented is a permissions layer, with a warning that shell runs with the host user’s filesystem, process and network authority and that directory inference from command text is best effort — so a narrow shell allowlist is the recommended boundary.
Still unsure? Write to [email protected] or use the contact form. Contact CmdBrief →
Primary sources
Provider terms and product behavior can change. Confirm plan, pricing, model, and permission details in the current official documentation.
- OpenCode documentation (v1)
- OpenCode documentation (v2)
- Migrating from OpenCode v1 to v2
- OpenCode v2: configuration
- OpenCode v2: instructions
- OpenCode v2: permissions
- OpenCode v2: models
- OpenCode v2: plugins
- OpenCode Go
- OpenCode Console
- OpenCode Zen
- OpenCode CLI reference (v1)
- anomalyco/opencode repository
- Crush (formerly opencode-ai/opencode)