Capital & Compute

OpenCode 2.0: What Changed and Should You Upgrade?

OpenCode 2.0 shipped on 11 September 2026 as a separate package, and V1 is still the default install. What changed, what breaks, and who should upgrade now.

· ai· coding-agents· open-source· pricing· By Capital & Compute
Resuming after a 30 minute break costs $0.16 with OpenCode cache warming against $0.50 without

The short answer. OpenCode 2.0 is real and shipping fast: @opencode/cli on npm went from 2.0.0 on 11 September 2026 to 2.0.28 on 13 October, 29 releases in 32 days. But it’s a separate package, and the default install still gives you V1. The opencode-ai package still tags 1.19.0 as latest, and the opencode.ai/install script still pulls the newest 1.x GitHub release. Upgrade now if you use OpenCode as a plain terminal agent. Wait if you depend on a V1 plugin, a custom server client, or LSP diagnostics, because all three break.

That gap between “released” and “default” is why the version question is confusing. OpenCode’s changelog now lists only 2.x releases and sends you to GitHub for “OpenCode 1 release notes.” The New Stack (OpenCode 2.0 puts its terminal, desktop, and web apps on one shared service, Paul Sawers, 12 October 2026) read that switch as V2 becoming the main line. Meanwhile, the package most guides tell you to install hasn’t moved.

What you’re asking OpenCode 1 OpenCode 2
Price Free, MIT Free, MIT
How you get it opencode.ai/install, npm opencode-ai opencode.ai/v2/install, npm @opencode/cli
Latest version 1.19.0 (11 October 2026) 2.0.28 (13 October 2026)
Command name opencode opencode (the V2 installer replaces V1)
Release notes GitHub Releases opencode.ai/changelog
V1 plugins Yes No, they must be ported
LSP diagnostics Yes Config is kept, but no language servers run

Sources: the npm registry entries for both packages and the OpenCode V2 install docs, read 14 October 2026.

Is OpenCode 2.0 stable or still a beta?

It’s past beta in practice, but nobody has put a “stable” label on it. Anomaly, the company behind OpenCode, publishes V2 to npm under the latest tag of the new @opencode/cli package, and the changelog treats 2.x as current. The OpenCode V2 docs don’t call it beta or stable anywhere. The one leftover is the Arch Linux package name, opencode-beta.

The docs used to say more. Earlier copies of the migration guide, still visible in search snippets, described a side-by-side beta: install from the next tag, run it as opencode2, expect that beta data might be wiped. The current guide says the opposite. Both versions use the opencode command, you remove a package-managed V1 install first, and the V2 curl installer replaces the V1 binary. If you followed a September tutorial that promised the two would coexist, that’s why your opencode now behaves differently.

The cleanest signal of intent is in V1 itself. OpenCode 1.19.0, released 11 October, adds opencode upgrade --major and a /update command in the TUI that can “upgrade to OpenCode 2.” It also stops installing updates automatically. Anomaly built a door from V1 to V2 and left it closed until you open it.

What’s new in OpenCode 2.0?

The biggest change is one you’ll mostly notice when something goes wrong. V2 runs a shared background service, and the terminal, desktop and web apps attach to it. The troubleshooting page says the shared server registers itself at ~/.local/state/opencode/service.json, keeps sessions in one database at ~/.local/share/opencode/opencode.db, and has its own opencode service status command. The build docs say that if you run OpenCode as a server, you connect with “the same client used by the TUI and desktop app.” That’s the change The New Stack’s headline describes: the terminal, desktop and web apps now sit on one service instead of each running its own.

The new agent features, all from the V2 tools reference and none present in the V1 docs as of 14 October:

  • Code Mode. A tool called execute lets the agent write JavaScript that calls and combines tools from its catalog, so a chain of tool calls can run as one script instead of one model turn per call. The sandbox is strict: no filesystem access, imports, timers or fetch. It can only reach the tools it’s been given.
  • Background subagents and shell commands. Set background: true on a subagent and it returns immediately, then notifies the parent when the child finishes. Background shell calls work the same way and have no timeout unless you set one.
  • Worktree tools. worktree_create, worktree_list and worktree_remove let the agent spin up a git worktree for parallel work and clean it up afterwards. They arrived in 2.0.27 on 12 October.
  • Cache warming. Optional keep-alive requests that stop a provider’s prompt cache from expiring while you’re away. This is the one with a price tag attached, so it gets its own section below.
  • Web pairing. opencode pair prints a local URL, username and password for the web app. Since 2.0.27, the first opencode pair --remote warns that it will expose your server and asks you to confirm.

The recent point releases are smaller: Google Cloud credentials for Vertex in 2.0.26, an installable web app in 2.0.27, then per-project auto-accept permissions, native Windows ARM64 builds and official WinGet packages (winget install --id Anomaly.OpenCode -e) in 2.0.28.

One thing that isn’t on this list: a faster or cheaper agent loop. Nobody has benchmarked OpenCode 2.0 against 1.x, and OpenCode wasn’t on any public harness leaderboard when this site compared it with Claude Code in July. Claims that V2 “uses fewer tokens” are unmeasured.

How does OpenCode 2.0 cache warming work, and does it save money?

Here’s what it fixes. You’re 40 minutes into a session with a large repo loaded and you step away for coffee. Ten minutes later you type your next prompt. On Anthropic’s API, the provider has already dropped the cached copy of your conversation: Anthropic’s prompt caching documentation gives cached content a 5-minute lifetime, measured from the start of the last request that used it. So your next turn re-writes the whole context at the cache-write rate, 1.25 times the normal input price, instead of reading it back at the discounted cache-read rate.

OpenCode V2’s warming sends a small keep-alive request with the session’s current model, agent, instructions and context, after 4 minutes with no model request, and repeats every 4 minutes until 30 minutes have passed since your last real request. The default prompt tells the model to do nothing and reply “OK,” and OpenCode throws the reply away. Each ping is a cache hit, and Anthropic says a cache hit refreshes the lifetime “for no additional cost.” Warming is off by default, and OpenCode’s own docs warn that pings “are real provider requests” that cost tokens and count against rate limits.

So the question is whether up to seven paid pings cost less than one cold re-write. On the newest Claude models it isn’t close.

Resume cost after a pause, with and without OpenCode cache warming (Opus 5.5, 100k tokens)Step chart. Without warming, resuming costs $0.02 up to 4 minutes, then jumps to $0.50 from 5 minutes on. With warming, the cost rises by $0.02 at each 4-minute ping and reaches $0.16 at 30 minutes.$0.00$0.20$0.40$0.600 min5 min10 min15 min20 min25 min30 minMinutes paused before your next promptCache expires (5 min)No warming$0.50 at 30 minWarming on$0.16 at 30 min
Resume cost after a pause, with and without OpenCode cache warming (Opus 5.5, 100k tokens). Cost to resume after each pause length, in dollars.
Minutes pausedNo warmingWarming on
0$0.02$0.02
4$0.02$0.04
5$0.50$0.04
10$0.50$0.06
15$0.50$0.08
20$0.50$0.12
25$0.50$0.14
30$0.50$0.16
Cost to resume an OpenCode session on Claude Opus 5.5 with a 100,000-token cached context, by how long you were away. Without warming, the cache expires at 5 minutes and the next prompt re-writes it for $0.50. With warming on (default 4-minute interval, 30-minute window), seven pings plus the resume read cost $0.16 at most. Prices: Anthropic pricing and prompt caching documentation, checked 14 October 2026.Source: Anthropic prompt caching documentation; OpenCode V2 warming docs

The arithmetic, for a 100,000-token cached context on Claude Opus 5.5 at $4 per million input tokens:

Event Rate Cost
One warming ping (cache read) 0.05× input = $0.20 / M $0.02
Seven pings, the full 30-minute window 7 × $0.02 $0.14
Cold resume, cache re-written 1.25× input = $5.00 / M $0.50
Warm resume, cache read 0.05× input $0.02

Opus 5.5 and Sonnet 5.5 read from cache at 0.05 times the base input price, half the 0.1× that most Claude models get, per the footnotes in Anthropic’s caching docs. That makes a ping cost 1/25 of a re-write. Warming only loses if you’d need more than 24 pings to save one re-write, and OpenCode’s default stops at seven. So if you come back inside the 30-minute window, warming always wins on these models. If you never come back, you’ve wasted $0.14.

That gives a cleaner rule than “turn it on” or “leave it off.” For a full 30-minute warm to pay for itself, you need to come back within the window in about 29% of your pauses on Opus 5.5 or Sonnet 5.5 (seven pings at 0.05×, against the 1.2× you save). On older Claude models with the 0.1× read rate, like Sonnet 4.6, the break-even rises to about 61%, so warming only makes sense if your breaks are usually short. The dollar amounts scale with context size: at 200,000 tokens, double every figure in the table.

To turn it on, add one line to opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "warming": true,
}

Two caveats on the maths. It assumes your whole session prefix is cached and that you pay Anthropic API rates, which is how most OpenCode users run Claude, since a Claude subscription can’t be used in third-party harnesses (covered in the OpenCode vs Claude Code comparison). It also ignores the keep-alive prompt and the “OK” reply, which cost well under a tenth of a cent per ping at these rates. For how fast cached context dominates an agent’s bill in the first place, see how many tokens AI coding agents actually use.

What breaks when you upgrade from OpenCode 1?

The migration guide lists three intentional breaking changes. Everything else in V1 that’s supported is supposed to keep working:

  1. Plugins. V2 has a new plugin API, and V1 plugin code doesn’t run. The guide is blunt: renaming the config entry or moving the file “is not enough.” Plugin authors have to port entrypoints, hooks, tools and events. Local plugins now load from .opencode/plugins/.
  2. The server API and its clients. If you wrote anything against OpenCode’s HTTP server, it has new contracts. The V2 API uses JSON over HTTP, with server-sent events for session logs.
  3. Terminal settings. The layered tui.json files become one global cli.json. This one migrates automatically.

The fourth break isn’t on that list, and it’s the one most likely to catch you out. Further down the same guide: V2 “accepts and preserves lsp configuration, but it does not run language servers, expose LSP tools, or produce LSP diagnostics.” If your workflow relies on the agent seeing type errors as it edits, V2 won’t show them. The guide’s advice is to have the agent run your linter, type checker or compiler instead. That works, but it’s slower, and it’s a real regression for TypeScript and Rust projects.

Your agents, commands, skills and .opencode/ files carry over. Fields that keep their shape, including shell, model, default_agent, formatter and instructions, need no changes.

Which config fields changed in OpenCode 2.0?

Most of the renames follow a pattern of singular to plural, plus a stricter permissions model. From the migration guide:

V1 field V2 field
autoshare: true share: "auto" (or "manual", "disabled")
permission (per tool) ordered permissions array
tool names bash, task, write/patch shell, subagent, edit
agent / mode agents
mcp mcp.servers (enabled becomes disabled)
provider providers
command commands
plugin plugins
compaction.preserve_recent_tokens compaction.keep.tokens
skills.paths + skills.urls one skills array
provider azure-cognitive-services azure
provider google-vertex-anthropic google-vertex

Watch the mcp change: enabled: false in V1 becomes disabled: true in V2. A careless find-and-replace that keeps the old value will switch your MCP servers on when you meant them off. The guide also says the quickest route is to ask OpenCode itself to convert your config, then check the diff.

How to upgrade to OpenCode 2.0

  1. Check your plugins first. List what’s in your config’s plugin array and in .opencode/plugin/. For each third-party plugin, check whether it has a V2 release. Some already support both: the cc-safety-net v2.4.3 release notes add OpenCode 2.0.6+ support next to V1 (1.18.29+). If a plugin you rely on has no V2 version, stop here.
  2. Back up your config. Copy opencode.json(c) and .opencode/ somewhere safe. The V2 installer replaces V1, so rolling back means reinstalling V1.
  3. Upgrade from inside V1. Update to 1.19.0, then run opencode upgrade --major, or use /update in the TUI. For a fresh machine, use one of the V2 install routes instead: curl -fsSL https://opencode.ai/v2/install | bash, npm install -g @opencode/cli, brew install anomalyco/tap/opencode-v2, or WinGet on Windows.
  4. Convert the config. Have OpenCode do it, then review the mcp, permissions and providers changes from the table above by hand.
  5. Run one real task. Pick something you did last week and run it in V2. Check that your MCP servers connect and your skills load, and that opencode service status reports a running service.
  6. Decide on warming. If you use Claude at API rates and often step away mid-session, set "warming": true. If you bill to a model with no cache-write premium, or your context is small, skip it.

Should you upgrade to OpenCode 2.0?

Upgrade now if you use OpenCode as a terminal agent with built-in tools and MCP servers, and especially if you run Claude at API rates: warming alone can cover the cost of a long session’s breaks. Background subagents and worktrees are a real step up for parallel work.

Wait if you depend on a plugin with no V2 release, if you’ve built tooling against the V1 server API, or if you rely on LSP diagnostics in a typed codebase. Nothing in the migration guide or changelog sets a retirement date for V1, and V1 still got a release on 11 October, so waiting a few weeks costs you nothing.

And if you’re choosing between OpenCode and Claude Code rather than between OpenCode versions, 2.0 doesn’t change the main trade-off. OpenCode is still free, MIT-licensed and works with any provider. Claude Code is still the one that runs on a Claude subscription. The comparison of OpenCode, Claude Code and OpenClaude and the best AI agent harnesses page cover that choice.

Frequently asked questions

When was OpenCode 2.0 released?
Version 2.0.0 of the @opencode/cli package was published to npm on 11 September 2026. It reached 2.0.28 on 13 October 2026. The original opencode-ai package still tags V1 (1.19.0) as latest, so the default install gives you V1 unless you choose the V2 installer or run opencode upgrade --major.
Is OpenCode 2.0 still in beta?
Not in practice. V2 ships under the latest npm tag of @opencode/cli and the official changelog lists only 2.x releases, but OpenCode has not labelled it stable either. Earlier docs described a side-by-side beta run as opencode2; the current docs say V2 replaces V1 under the same opencode command.
How do I upgrade OpenCode to version 2?
Update V1 to 1.19.0 and run opencode upgrade --major, or use /update in the TUI. On a fresh machine, install with curl -fsSL https://opencode.ai/v2/install | bash or npm install -g @opencode/cli. Check that your plugins have V2 versions first, because V1 plugins do not run in V2.
Do OpenCode 1 plugins work in OpenCode 2?
No. V2 has a new plugin API, and the migration guide says renaming the config entry or moving the file is not enough: plugin code must be ported. Agents, commands, skills and most config files carry over unchanged.
Does OpenCode 2.0 support LSP?
It keeps your lsp configuration but does not run language servers, expose LSP tools or produce LSP diagnostics. The migration guide recommends replacing those workflows with the project lint, typecheck or compile commands.
Is OpenCode cache warming worth turning on?
On Claude Opus 5.5 or Sonnet 5.5 at API rates, usually yes. A warming ping costs 1/25 of a cache re-write, so a full 30-minute warm (seven pings) pays for itself if you come back within the window in about 29% of your pauses. On older Claude models with a 0.1x cache-read rate the break-even is about 61%.

Sources

Get each breakdown before it makes the rounds

You get one email when a new source-backed analysis goes live: what AI agents actually cost, which models are worth running, and what the benchmarks really mean. No hype.

No spam. Unsubscribe anytime.

← Back to Coding agents