Playbooks · Coding tasks
Move OpenCode 1.x to 2.0 without losing config
Written October 29, 2026
For a v1 user × migrating to OpenCode 2.0 without losing plugins, config, or shared rules × OpenCode 2.0, ending with the 2.0 setup running the same models, agents, permissions, and rules the 1.x setup had.
Before you start
OpenCode 1 and OpenCode 2 both use the opencode command and are no longer installed side by side by default. OpenCode's migration guide states the shape of the change: V2 has three intentional breaking changes — plugins use a new plugin API, the server API and clients have new contracts, and terminal client configuration moves from layered tui.json(c) files to one global cli.json file, auto migrated. Existing supported server config fields, agent definitions, command definitions, skills, and other files in .opencode/ should continue to work without changes. V1 plugin implementations do not run in V2: moving a file or renaming its config entry is not enough, and a V1 plugin left in place warns that it failed to load instead of running.
Two more changes catch migrating users. V2 discovers AGENTS.md only: if a V1 setup relied on a CLAUDE.md fallback, that guidance must move into the applicable AGENTS.md. And V2 replaces layered V1 tui.json(c) files with one global terminal client configuration file, ~/.config/opencode/cli.json; when cli.json is absent, the first V2 terminal client startup migrates supported global tui.json settings while leaving V1 files unchanged. Project-local client configuration is not migrated, because V2 client configuration is global.
What "done" looks like
At the end of one sitting V2 starts cleanly, the models, credentials, agents, permissions, and MCP servers from the 1.x setup are confirmed working, every V1 plugin is either ported or deliberately dropped, and the shared rules live in AGENTS.md files V2 actually reads. The copy of the V1 setup is still on disk, untouched.
Steps
- Copy the V1 setup before touching anything. Copy the whole OpenCode configuration — the global config directory and the project's
.opencode/folder,opencode.json,AGENTS.md, andCLAUDE.mdif one exists — to a backup folder outside the project. V1 and V2 use the same configuration locations, so do not point V1 at files after converting them to V2-only shapes. The backup is what makes the rest of the migration reversible. - Inventory what the setup actually contains. List, from the copied files: the plugins and where each one is configured, the permission rules, the agents and commands, the MCP servers, and any
CLAUDE.mdfile the setup relies on. The migration guide's checklist for the first V2 start is models, credentials, agents, permissions, and MCP servers — the inventory is that checklist, written down before the install. - Remove a package-managed V1 install, then install V2. Remove a package-managed V1 installation before installing V2, then install V2 with the V2 installer:
curl -fsSL https://opencode.ai/v2/install | bash. The V2 curl installer replaces the V1 binary. OpenCode's installation instructions list the other install methods, including npm, Bun, pnpm, and mise. After installing, start V2 once and work through the inventory: confirm each model, credential, agent, permission rule, and MCP server appears and behaves as it did. Existing supported server config fields, agent definitions, command definitions, skills, and other files in.opencode/should continue to work without changes — anything that does not is a migration gap to fix, not a setting to retype from memory. - Let V2 migrate the client config, then check the result. If no
cli.jsonexists, the first V2 terminal client startup migrates supported globaltui.jsonsettings and persisted preferences into~/.config/opencode/cli.json, leaving the V1 files unchanged. Open the newcli.jsonand compare it with the globaltui.json: theme and keybinds should have carried over, with renamed keys in their new form. Project-localtui.jsonsettings do not migrate — move anything project-local that matters into the global file by hand, and delete nothing from the backup copy. - Move
CLAUDE.mdguidance intoAGENTS.md. ExistingAGENTS.mdfiles stay in place, and V2 discovers the global~/.config/opencode/AGENTS.mdand ambientAGENTS.mdfiles. Copy the guidance from eachCLAUDE.mdthe setup relied on into the applicableAGENTS.md, then confirm theCLAUDE.mdfile is no longer the only copy of any rule. A rule left only inCLAUDE.mdis a rule V2 never reads. - Port each plugin; do not just move it. V1 plugin implementations do not run in V2. The plugin migration guide gives the port: change the package import to
@opencode/plugin, replace the exported plugin function withPlugin.definecarrying a stableid, and move initialization intosetup. In config, renameplugintopluginsand replace a package-and-options tuple with an object. V2 discovers local plugins from both.opencode/plugin/and.opencode/plugins/; use.opencode/plugins/for V2 files, and note that configured local paths must be directories, so a ported plugin lives at a path such as./plugin/local/index.ts. Start V2 after each port and confirm the plugin loads without a failure warning before porting the next one. A plugin that cannot be ported is dropped deliberately and noted in the inventory, not left in place to warn on every start. - Check the behaviour changes that have no config error. Three V2 changes take effect silently. Permissions are now one ordered
permissionsarray: V1 grouped permission effects by tool, sobashbecomesshell,taskbecomessubagent, andwrite/patchbecomeedit— confirm the converted rules still say what the V1 rules said. Todos are off by default in V2; turn them on with the experimental flag if the setup used them. V1 asked before accessing paths outside the project; V2 does not, becauseexternal_directoryis allowed by default — decide whether that default stands for each project before the first real task. Language-server config is accepted and preserved, but V2 does not run language servers or produce LSP diagnostics. - Do not plan around share links. Sharing has been discontinued: OpenCode's SDK reference lists the share endpoint as returning an error. Existing share links and share commands are unavailable in V2. If the V1 workflow shared sessions by link, replace that step — a pasted transcript, a saved session file, or a screen share — before deleting the backup.
Check the agent's work
- Check that the backup copy exists and matches the pre-migration setup, file for file, before any converted file is relied on.
- Check that every plugin in the inventory is ported, dropped deliberately, or still warning on start — with no plugin silently absent.
- Check that no rule lives only in a
CLAUDE.mdfile. Search forCLAUDE.mdfiles in the project and confirm each one's guidance also sits in anAGENTS.md. - Check that
cli.jsoncarries the globaltui.jsonsettings, and that project-local settings were handled by hand rather than assumed migrated. - Check that the permission rules read the same after conversion: same actions, same resources, same effects, under the new names.
What can go wrong
- Pointing V1 at converted files. V1 and V2 share configuration locations. Converting in place and then opening V1 corrupts the rollback. Convert copies; validate V2; keep the backup until V2 is confirmed.
- Moving a plugin instead of porting it. A V1 plugin file moved into the V2 folder still does not run. The import, the
Plugin.defineform, and the config rename are all part of the port. - Assuming project-local client config migrates. Only supported global
tui.jsonsettings migrate, and only into the globalcli.json. Project-local settings are left behind silently. - Leaving rules in
CLAUDE.md. V2 discoversAGENTS.mdonly. The fallback is gone, and the rules with it. - Keeping share links in the workflow. Sharing is discontinued and the endpoint returns an error. A workflow step that depends on it fails at the moment it is needed.
Limits
- This page follows OpenCode's migration guides. Where the installed V2 and a guide disagree, the guide for the installed version is the authority, and the disagreement is a gap to record, not a detail to guess.
- The ported plugin form needs the
@opencode/pluginpackage available to the plugin before it runs. A ported file without its package is a file that does not load. - Server API and client changes beyond the plugin and config shapes above are outside this page. Code that called the V1 server API needs the revised V2 API, documented separately from the migration guide.
Related playbooks
- OpenCode 2.3.0: subagents move to the background
- OpenCode 2.3.2 stops re-billing the system prompt
- Use Claude Code login inside OpenCode
- OpenCode 2.2.7: Copilot Auto and breaking changes
Sources
Sources: Migrate from V1 — OpenCode, Migrate plugins from V1 — OpenCode, OpenCode SDK reference.
Back to: Coding playbooks hub · Also: Build a small CLI tool end to end with an agent