OpenCode 2.0 works as a single background server shared by the terminal, web, and desktop app, brings a rebuilt API that the agent itself can call, and adds Code Mode, background subagents, and a new plugin system. To update, move to the latest 1.x and run opencode upgrade --major. We did it on a real macOS installation and tested every feature with a free model, for a total cost of $0.00.
yoDEV Tested · October 14, 2026
We updated a real macOS installation from 1.17.11 to OpenCode 2 and repeated tests in a clean Linux environment with@opencode/cli2.0.29. The results we report as ours come from that test.
Anomaly announced OpenCode 2.0 on October 12, 2026, but the package predates the announcement: @opencode/cli 2.0.0 appeared on npm on September 11, and the current version when we tested on October 14 was 2.0.29.
What is OpenCode?
OpenCode is an open-source AI coding agent that runs in your terminal, in the browser, and as a desktop app, and connects with dozens of model providers, including its own, OpenCode Zen, which offers free models. If you’re comparing it to other terminal agents, our OpenCode vs Crush comparison covers the 1.x line.
How do I update OpenCode to version 2.0?
The update takes two steps, because the --major option only exists in recent 1.x versions; the upgrade command in version 2 doesn’t have it.
First, back up your configuration:
cp -r ~/.config/opencode ~/.config/opencode.v1-backup
Then bring 1.x up to date and jump to 2:
opencode upgrade
opencode upgrade --major
opencode --version
In version 1.19.0, the help for --major says it updates to OpenCode 2 and removes OpenCode 1. That is, it replaces v1: the two versions don’t coexist installed. If you installed via npm, note that the package name changes: v1 was opencode-ai and v2 is @opencode/cli.
Our test: 1.17.11 → opencode upgrade → 1.19.0 → opencode upgrade --major → OpenCode 2. We repeated the second step with --method npm in a clean Linux environment, where it removed opencode-ai and left only @opencode/cli installed.
How do I install OpenCode 2.0 from scratch?
If you’ve never used OpenCode, you can install version 2 directly from npm, with the same command the official documentation uses in its CI example:
npm install --global @opencode/cli
Then enter a project folder and run opencode to open the terminal interface.
What breaks when updating to OpenCode 2.0?
The migration guide lists exactly three breaking changes, all intentional:
- Plugins. Plugin implementations from v1 don’t work in v2. The configuration key also changes from
plugintoplugins, but renaming it isn’t enough: each plugin has to be ported with the plugin-specific migration guide. (We didn’t test a v1 plugin; this is what the provider’s documentation indicates). - The server API. Anything that calls the v1 server API has to move to the v2 API, through the new
@opencode/clientpackage. - Terminal client configuration. Layered
tui.jsonfiles are replaced by a single global file,~/.config/opencode/cli.json, which is migrated automatically the first time v2 terminal starts.
If you depend on any OpenCode plugin, review it before updating. Our list of 10 OpenCode plugins and agents worth installing was written for 1.x.
Does my OpenCode 1.x configuration still work?
Yes. v2 reads configuration from the same locations as v1 and normalizes the old format in memory, without rewriting your files. On our test machine, the existing opencode.jsonc survived the update intact and v2 worked with it as-is. In a separate test, a v1 agent defined with prompt was read as system in v2, and an MCP server in v1 format connected normally.
Converting your configuration to v2’s native format is optional. The migration guide recommends letting OpenCode do it with this prompt:
Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format.
Preserve its behavior and all unrelated settings.
Before using v2 daily, it’s worth knowing two behavior changes:
- v2 only reads
AGENTS.md. If your v1 configuration relied on aCLAUDE.mdfile as a fallback, move those instructions toAGENTS.md. - v2 doesn’t run language servers. It accepts
lspconfiguration, but doesn’t start them or produce LSP diagnostics; the documentation suggests using your project’s lint, typecheck, or compile commands instead.
What is Code Mode in OpenCode?
Code Mode lets the agent write a short JavaScript script that calls several tools at once, instead of calling them one by one, with a round trip for each call. It runs on a minimal interpreter included in the @opencode/codemode package, which turns MCP servers and OpenAPI endpoints into functions the script can invoke. In 2.0, all MCP servers come with Code Mode enabled by default.
Our test. We added the Context7 MCP server with a single command, nothing else:
opencode mcp add context7 --url https://mcp.context7.com/mcp
Then we asked OpenCode to compare how React and Vue handle state using Context7. The first execute block sent both queries, React and Vue, together. The React one failed because Context7 moved React’s identifier from /facebook/react to /react/react; the second execute block retried with the correct identifier and launched two React queries at once. In total: four MCP calls in two round trips, where calling them one by one would have taken four.
Anomaly also claims Code Mode lets you add a thousand MCP servers with minimal context impact. That’s the provider’s claim; we tested with one server.
Can OpenCode run tasks in the background?
Yes, both subagents and shell commands. The main agent can delegate work to a background subagent (automatically or when you ask, even with a different model) and keep working. Long shell commands can also run asynchronously, and any command or foreground subagent can be sent to the background with ctrl+b.
Our test. We asked for a background subagent to review README.md while sleep 45 was running, and the agent answered a second prompt with both still in progress. Then we launched a sleep 60 in the foreground and pressed ctrl+b: it moved to the background instantly. Around a minute later, the transcript showed ↳ Shell finished · sleep 60 and the agent confirmed it without being asked.
How does OpenCode create a git worktree on its own?
OpenCode 2.0 knows its own API and uses it. The example from the announcement is moving the current session to a new git worktree when you start new work, and that’s exactly what we saw.
Our test. We asked: “Start rate limiting uploads in a new worktree.” The agent ran opencode.worktree_create [name=rate-limit-uploads] inside an execute block, and then opencode.session_move to the new directory, ~/.local/share/opencode/worktree/<project>/rate-limit-uploads. In other words, it handled its own API through Code Mode. (The rate limiting itself didn’t progress: our test repository has no file upload endpoint).
You can call the same API yourself with opencode api:
opencode api session.list --param limit=10
opencode api session.create --data '{"title": "New session"}'
What is the OpenCode background service?
In 2.0, OpenCode starts a single shared background server for your user account, and all local clients (terminal, web, and desktop) connect to it. That server owns the sessions, configuration, integrations, permissions, and tool execution; that’s why a session you start in the terminal also appears in the web interface.
You manage it with opencode service:
opencode service status
opencode service start
opencode service stop
If you prefer the previous behavior, with one process per terminal, opencode --standalone runs a private server, and opencode service set disabled true makes it the default behavior. opencode pair prints one-time links and a QR code to connect another browser or app to the server.
What changes in OpenCode 2 plugins?
The plugin system was rebuilt, and Anomaly implemented nearly all 2.0 features as internal plugins to keep the API in good shape. Querying our installation through the API we got 88 built-in plugins, including ones for worktrees, Code Mode defaults, and subagents. (At the time we tested, opencode plugin list --builtin showed no plugins in the same session; the API listing is the reliable one).
Plugins for the terminal interface moved from experimental to stable, and everything can be hot-reloaded, so OpenCode can write a plugin for itself mid-session and use it right away. Plugins are managed with opencode plugin add, opencode plugin list, opencode plugin check, and opencode plugin update.
There’s also a new package, @opencode/sdk, to use OpenCode as a library: it’s the same code that powers the CLI. At the time of publishing this note, Anomaly described it as still in development.
Is OpenCode free?
OpenCode is open source, and its built-in provider, OpenCode Zen, includes free models that work without an API key. All agent tests in this article were done with Big Pickle (opencode/big-pickle), one of those free models, and opencode stats --cost --days 1 reported $0.00 for the day: about 120,000 input tokens and 13,000 output tokens, with 90 percent of the input served from cache. The list of free models changes; run opencode models to see the current one.
How did we test?
- Update and agent features: Greg’s macOS installation, updated from 1.17.11 on October 14, 2026, with Big Pickle in the default Build agent.
- API, built-in plugins, and v1 configuration compatibility: a clean Linux environment with
@opencode/cli2.0.29.
And you? Which of OpenCode 2.0’s new features will you use first in your workflow?
- Yes, I’m already on 2.0
- Not yet: waiting for my plugins to update
- I use another coding agent
- I prefer another option (tell us which)
Comment below or, if you got this article by email, reply directly to the email: your reply is published here.
Related: Your OpenCode Is Empty: 10 Plugins and Agents Worth Installing