How to Upgrade to OpenCode 2.0: Migrate Your v1 Config, Plugins, and Sessions

Name

Soren Atelier

Updated on 11/4/2026

The short answer: back up your OpenCode folders, update to the latest 1.x release, then run the major upgrade.

# 1. Back up config and data (sessions live in the data folder)
cp -R ~/.config/opencode ~/opencode-v1-config-backup
cp -R ~/.local/share/opencode ~/opencode-v1-data-backup
 
# 2. Get onto the latest 1.x first (--major exists from v1.19.0)
opencode upgrade
 
# 3. Move to OpenCode 2
opencode upgrade --major

Inside the terminal UI, /update does the same thing. If you would rather do a clean install, remove the v1 package first, then use one of the v2 install commands in Step 3.

Most v1 settings keep working. Three things break on purpose: v1 plugins do not load, the server API is new, and tui.json is replaced by cli.json. Two quieter changes catch people off guard: v2 no longer reads CLAUDE.md, and it allows access to folders outside the project by default. The rest of this guide covers each one, plus the known bugs from the first weeks of 2.x.

What we checked and what we did not: On October 25, 2026, we checked the v1 side on macOS with OpenCode 1.18.19 installed. We read its upgrade, export, session, and debug paths commands. We also read the npm registry data for @opencode/cli 2.1.4 and the GitHub issues and maintainer replies cited below. We did not run OpenCode 2 for this guide. Everything about v2 behavior comes from the official migration guide (opens in a new tab), the v2 docs (opens in a new tab), the OpenCode 2.0 announcement (opens in a new tab), and those maintainer replies. We link each source. On November 4, 2026, we re-checked the versions, release pages, and issue threads against @opencode/cli 2.2.5 and opencode-ai 1.19.5.

Should you upgrade now?

OpenCode 2.0 reached npm on September 11, 2026, as @opencode/cli. Many v1 users who installed through npm or the install script only saw it in October (Homebrew core users got it earlier; see the Homebrew trap in Step 3). That's because the opencode upgrade --major path arrived in v1.19.0 on October 11, and the team announced 2.0 on October 14. The announcement reached 888 points on Hacker News. Since October 11, the repo has received over 4,000 new issues, and 130 of them mention 2.0.

The two versions now ship side by side. opencode-ai on npm is still v1 (1.19.5 on October 28). @opencode/cli is v2 (2.2.5 on October 30). Since v2.2.0 (October 27), 2.x builds also appear on GitHub Releases (opens in a new tab), but the release marked Latest is still 1.x. This is deliberate: v1 looks for updates through the Latest release, and the team does not want v1 auto-update to jump users to 2.x (#57675 (opens in a new tab)).

Step 1: Back up before you touch anything

The official migration guide says to keep a copy of your v1 setup while you test. It does not say what to copy. On macOS and Linux, opencode debug paths lists the folders. Our 1.18.19 install showed:

Copy the first two (the commands at the top of this page). Quit OpenCode first, so the session database (opencode.db and its -wal file) is copied in a consistent state. Also copy any project-level opencode.json and .opencode/ folders you care about. Those stay in your repos, so git already tracks them in most cases.

To get a portable copy of an important conversation, export it from v1 before you upgrade:

opencode session list
opencode export <sessionID> > my-session.json

opencode export writes the session as JSON. Add --sanitize to strip sensitive transcript and file data before you share the file.

Step 2: Get onto the latest 1.x

opencode upgrade --major only exists from v1.19.0. On our 1.18.19 install, opencode upgrade --help showed no --major flag. If you are on 1.18 or older, run a plain upgrade first:

opencode --version
opencode upgrade

Then check that opencode --version prints 1.19.x. Since v1.19.0, updates no longer install themselves, so an old install stays old until you run this.

Step 3: Upgrade or install v2

In-place upgrade (from 1.19.x):

opencode upgrade --major

Clean install. The migration guide says to remove a package-managed v1 install first, because v1 and v2 do not install side by side by default. Then pick one of the official v2 commands:

# Official installer (replaces the v1 binary)
curl -fsSL https://opencode.ai/v2/install | bash
 
# Homebrew (note the -v2 formula; remove a v1 brew install first)
brew uninstall opencode
brew install anomalyco/tap/opencode-v2
 
# npm (new package name)
npm uninstall -g opencode-ai
npm install -g @opencode/cli

Package-manager traps:

• npm package name. v1 is opencode-ai. v2 is @opencode/cli. If you run npm install -g opencode-ai today, you still get 1.19.5.
• Homebrew core vs. the tap. brew install opencode (no tap) has installed OpenCode 2 since September 28, so brew upgrade already moves that install to 2.x without --major. The 1.x formula is anomalyco/tap/opencode and the 2.x one is anomalyco/tap/opencode-v2. They conflict, so run brew uninstall opencode before you install the other one.
• Install scripts. The v2 npm package uses a postinstall script to pick the native binary. If you use Bun or pnpm, add --trust (Bun) or --allow-build=@opencode/cli (pnpm). Without that flag, the binary is missing.
• Two command names. The npm package registers both opencode and opencode2 in its bin field (we checked the registry metadata).
• mise installs v2 only from mise 2026.10.9. Older mise versions install OpenCode 1.
• Windows package managers (Scoop, Chocolatey) are not supported for v2, and opencode upgrade --major cannot switch those installs. Download the standalone Windows CLI binary or the desktop app from the v2 install page (opens in a new tab), or use WSL. A Chinese-language report of v2 hanging under WSL (#55033 (opens in a new tab)) was closed on October 16 for missing details.
• Docker: versioned images exist, for example ghcr.io/anomalyco/opencode:2.0.0.

Run opencode --version and confirm it prints 2.x.

Step 4: Check what v2 picked up from your v1 config

You do not have to rewrite your config. v1 and v2 read the same locations (~/.config/opencode/opencode.json, project opencode.json, .opencode/). v2 maps v1 field names in memory and does not rewrite your files. On the first v2 start, global tui.json settings move into a new ~/.config/opencode/cli.json. Your v1 files stay as they were.

Open a real project and check five things before you trust it: models, provider credentials, agents, permissions, and MCP servers. The migration guide uses the same checklist.

If you later want native v2 config, these are the field changes that matter most:

Two rules from the guide prevent most migration mistakes:

1. Keep each entry in one format. You can mix v1 and v2 syntax at the top level. Inside a single agent, provider, command, or model entry, pick one format.
2. Do not point v1 at a converted file. Both versions read the same paths. Once you convert a file to v2-only syntax, v1 can no longer read it. If you plan to roll back, convert last.

The guide also suggests letting OpenCode do the conversion itself. Start v2 in the project and give it 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." Review the diff before you keep it.

v1 fields that v2 ignores

These print a warning and do nothing:

Agent-level temperature, top_p, and options also stop working. v2 keeps them in the agent's request.body but does not send them. Set them on a model variant instead.

These v1 fields look old but still work without a warning, because v2 converts them for you. Do not delete them during cleanup:

LSP config is kept but not run. If you relied on OpenCode's LSP diagnostics, give the agent explicit lint, typecheck, or compiler commands instead (for example in AGENTS.md).

Step 5: The behavior changes that bite later

Nothing errors when these change, so they cause the most surprises.

v2 does not read CLAUDE.md

v1 fell back to CLAUDE.md when no AGENTS.md existed. v2 does not. If your project rules live in CLAUDE.md, v2 starts without them, and nothing warns you. The fix takes one minute:

# In each repo that only has CLAUDE.md
git mv CLAUDE.md AGENTS.md

v1 also used ~/.claude/CLAUDE.md as global rules when ~/.config/opencode/AGENTS.md was missing. v2 dropped that fallback too. If you have no global AGENTS.md, copy it there:

cp ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md

Claude Code now reads AGENTS.md when no CLAUDE.md is present, so one file can still serve both tools. The setup is in Claude Code Reads AGENTS.md. The feature request to restore the fallback is open as #53402 (opens in a new tab).

Folders outside the project are allowed by default

In v1, the agent asked before it touched a directory outside the project. In v2, external directory access is allowed by default. To restore the v1 behavior, add this rule to permissions:

{
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

If you run OpenCode with auto-approve, or on a machine with sensitive files outside your repos, add this rule before your first v2 session.

Todos are off

The todo list was on by default in v1. In v2 it is off. Turn it back on with "experimental": { "todo": true }.

One background service now runs for your whole user account

v2 starts one shared background server. The TUI, the web UI, and the desktop app all connect to it. That is what makes opencode pair (a one-time link that expires after 5 minutes) and background tasks (Ctrl+B) work. If you would rather not have it:

opencode service set disabled true   # stop it and stop auto-start
opencode service unset disabled      # turn it back on
opencode --standalone                # one private server for this run only

Pairing does not work while the service is disabled. The service also does not read cli.json, so terminal UI settings only affect the terminal client.

Step 6: Plugins, Oh My OpenCode, and the VS Code extension

v1 plugins do not load in v2. The plugin API is new. Renaming plugin to plugins in your config is not enough. Each plugin's code has to be ported (see the official plugin migration guide (opens in a new tab)).

The most common failure was Oh My OpenCode (oh-my-openagent). On OpenCode 2.0.27, version 5.1.32 failed with Plugin must export a default definition with an id and an effect or setup function (oh-my-openagent #10089 (opens in a new tab)). The fix (#10439 (opens in a new tab)) merged on October 18, and 5.1.38 is the first npm release that includes it. On November 2 the maintainer confirmed that current versions load on OpenCode 2 and show a notice pointing to OmO Native, the standalone omo app. Update oh-my-openagent to 5.1.38 or later before you upgrade OpenCode. If you would rather move to omo, its README says to run omo setup once to carry over provider keys, MCP servers, skills, and model picks. If you are new to the harness itself, start with Oh My OpenCode and OpenCode: Install, Setup, and Fixes.

VS Code extension error Unrecognized flag: --port. Older versions of the extension start the CLI with opencode --port <port>. v2 removed that flag. Update the extension to v1.0.0 or later (Marketplace or Open VSX). Until you do, open a terminal in VS Code and run opencode yourself (#55219 (opens in a new tab)).

Your own scripts that call the server. The v1 server API is gone. Port them to the @opencode/client package, which also finds the background service on its own. From the shell, opencode api calls the same API. OPENCODE_SERVER_USERNAME is no longer supported; the username is always opencode. The OpenCode GitHub Action was removed in 2.2.0.

Known problems after upgrading

These are open or recently fixed GitHub issues from the first weeks of 2.x. The fixes come from maintainers, reporters, or the project's bot in each thread.

How to roll back to 1.x

The migration guide does not cover going back. This is the safe order:

1. Remove v2. opencode uninstall --dry-run shows what it will remove. opencode uninstall then removes the program and leaves sessions, config, and state on disk.
2. Reinstall v1 with a pinned version: npm install -g opencode-ai@1.19.5, or brew install anomalyco/tap/opencode (the formula without -v2).
3. If you converted any config file to v2-only syntax, restore it from ~/opencode-v1-config-backup.
4. If v1 cannot read the session database after v2 has used it, restore ~/opencode-v1-data-backup. We did not test whether v1 opens a database that v2 has written to. Plan for the backup.

Security note: the OpenCode Console breach

This is separate from the upgrade, but it happened in the same week. On October 17, the OpenCode team said someone gained unauthorized access to a legacy system it was decommissioning (statement quoted on Hacker News (opens in a new tab)). Third-party provider keys saved in a Console workspace "may have been exposed." Their advice: revoke and replace those keys in each provider's dashboard and review recent usage. A later post put the share of affected Console users at 1.4%, and co-founder Dax Raad said the CLI and desktop app were not affected (TechCrunch (opens in a new tab)). If you ever saved OpenAI, Anthropic, or other keys in the Console, rotate them before or after you upgrade.

What is actually new in 2.0

You do not need any of this to finish the upgrade. These are the features that explain why the architecture changed:

• Background service shared by the TUI, web UI, and desktop app, plus opencode pair for web access.
• Background tasks: press Ctrl+B to send a running shell command or subagent to the background while the main agent keeps working.
• Code Mode: turns MCP servers and OpenAPI endpoints into functions that the agent can chain in one step. MCP servers use it by default.
• Hot reload: OpenCode can write a plugin for itself mid-session and use it immediately.
• @opencode/sdk and @opencode/client: the code behind the CLI, for building your own clients.

If you are choosing a terminal agent from scratch rather than upgrading one, How to Use Codex and How to Use Pi Coding Agent cover the closest alternatives.

Related Guides

• Oh My OpenCode and OpenCode: Install, Setup, and Fixes
• Claude Code Reads AGENTS.md: Share One File with Codex, OpenCode, and Cursor
• How to Use Codex
• How to Use Pi Coding Agent 1.0
• How to Use DeepSeek Harness
• Parallel Code Agents Explained