# OpenCode in 2026: v1 vs v2, plans, and which one you mean

> The open-source terminal coding agent, now published by Anomaly and now on v2. Install, the Go and Console plans, models, worktrees, agents and sessions, checked September 2026.

- **Category:** Workflows
- **Updated:** 2026-09-22
- **Reading time:** 11 min
- **Canonical page:** https://cmdbrief.com/guides/opencode

## 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. |

*Read from the GitHub API, both repositories and the npm registry on 22 September 2026. Anomaly asks projects that use “opencode” in their name to state in their README that they are not built by or affiliated with the OpenCode team; several sites that look like official documentation are not linked from opencode.ai.*

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

> **Warning:** From the migration guide, verbatim: “OpenCode 1 and OpenCode 2 both use the `opencode` command and are no longer installed side by side by default. Remove a package-managed V1 installation before installing V2; the V2 curl installer replaces the V1 binary.” Both lines are actively shipping — v1 reached `1.18.32` on 21 September 2026 and v2 reached `2.0.13` on 22 September 2026 — so “latest” is ambiguous unless you say which line you mean.

**Install OpenCode v1**

```bash
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/opencode
```

**Install OpenCode v2**

```bash
curl -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.0
```

The 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. |

*From the v1-to-v2 migration guide, read 22 September 2026. There is no tagged v2.0.0 GitHub release; the v2 line ships through npm and the v2 installer while GitHub Releases still carries only the v1 tag series.*

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`, and `opencode auth login` walks you through it with `--provider` and `--method` flags.
- Connect a subscription from inside the interface: “Run the `/connect` command 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 |

*From the v2 Go documentation, read 22 September 2026. These limits are denominated in dollars of inference, not in requests. The v1 Go page lists a longer model set and per-model monthly limits instead, with the 5-hour window at 20 per cent and the weekly at 50 per cent of the monthly figure; the two pages disagree, and these are the v2 numbers.*

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.

> **Tip:** Dollar-denominated windows are unusually easy to reason about. A rolling window, a weekly window and a monthly window is also exactly the shape CmdBrief draws for OpenCode Go plans, which means the meter in the workspace and the limit in your account are describing the same thing in the same units — not something you can say about most agent subscriptions.

## 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](https://cmdbrief.com/guides/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](https://cmdbrief.com/guides/agent-cli-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.

> **Tip:** That design choice has a downstream consequence worth naming. Claude Code, Codex, Grok Build, Kimi Code and Cursor CLI all let an external supervisor drop a hook file in and be told when the agent starts, stops or needs input. OpenCode does not expose an equivalent, which is why CmdBrief detects OpenCode’s state from the process and the screen instead of from a hook.

## 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](https://cmdbrief.com/guides/claude-code-sandbox) sets out how to match authority to consequence, and it applies here even though the mechanism differs.

## Sessions, headless runs and server mode

**Non-interactive and session management**

```bash
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 db
```

Sessions 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

> **Warning:** From the v2 instructions documentation, verbatim: “OpenCode V2 recognizes `AGENTS.md` only. It does not use `CLAUDE.md` as a fallback.” v1 does fall back — a project `CLAUDE.md` when there is no `AGENTS.md`, and `~/.claude/CLAUDE.md` when there is no global `AGENTS.md`, both disableable by environment variable. If you upgrade a repository that only ever had a `CLAUDE.md`, the agent silently stops reading your house rules.

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](https://cmdbrief.com/guides/kimi-cli) is the only other one that reads `AGENTS.md` and nothing else; [Grok Build](https://cmdbrief.com/guides/grok-cli) sits at the opposite extreme and reads every Claude-shaped file as well.

## Where CmdBrief fits

CmdBrief runs Claude Code, Codex, Grok CLI, Kimi CLI, OpenCode and Cursor CLI in one Mac workspace (Claude, Codex, Grok and Cursor can lead; OpenCode joins as a crew member), 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](https://cmdbrief.com/guides/claude-code-vs-codex) covers the two most people already pay for, [running two agents in parallel](https://cmdbrief.com/guides/run-claude-code-and-codex-in-parallel) is the worktree pattern that keeps them out of each other’s way, and [the tool comparisons](https://cmdbrief.com/compare) 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.

## Primary sources

Provider terms and product behavior can change. Confirm plan, pricing, model, and permission details in the current official documentation.

- [OpenCode documentation (v1)](https://opencode.ai/docs/)
- [OpenCode documentation (v2)](https://opencode.ai/v2/docs)
- [Migrating from OpenCode v1 to v2](https://opencode.ai/v2/docs/migrate-v1/)
- [OpenCode v2: configuration](https://opencode.ai/v2/docs/config/)
- [OpenCode v2: instructions](https://opencode.ai/v2/docs/instructions/)
- [OpenCode v2: permissions](https://opencode.ai/v2/docs/permissions/)
- [OpenCode v2: models](https://opencode.ai/v2/docs/models/)
- [OpenCode v2: plugins](https://opencode.ai/v2/docs/plugins/)
- [OpenCode Go](https://opencode.ai/v2/docs/console/go/)
- [OpenCode Console](https://opencode.ai/v2/docs/console/)
- [OpenCode Zen](https://opencode.ai/docs/zen/)
- [OpenCode CLI reference (v1)](https://opencode.ai/docs/cli/)
- [anomalyco/opencode repository](https://github.com/anomalyco/opencode)
- [Crush (formerly opencode-ai/opencode)](https://github.com/charmbracelet/crush)

## Keep reading

- Comparisons: [Agent CLI comparison (2026): six terminal coding agents](https://cmdbrief.com/guides/agent-cli-comparison)
- Workflows: [Kimi CLI is now Kimi Code CLI: the 2026 guide](https://cmdbrief.com/guides/kimi-cli)
- Workflows: [Cursor CLI (2026): the agent binary, worktrees, hooks and quota](https://cmdbrief.com/guides/cursor-cli)

---

Markdown mirror of https://cmdbrief.com/guides/opencode, generated at build time from the same data the HTML page renders. Machine-readable index: https://cmdbrief.com/llms.txt