Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

  1. 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, and CLAUDE.md if 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.
  2. 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.md file 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.
  3. 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.
  4. Let V2 migrate the client config, then check the result. If no cli.json exists, the first V2 terminal client startup migrates supported global tui.json settings and persisted preferences into ~/.config/opencode/cli.json, leaving the V1 files unchanged. Open the new cli.json and compare it with the global tui.json: theme and keybinds should have carried over, with renamed keys in their new form. Project-local tui.json settings do not migrate — move anything project-local that matters into the global file by hand, and delete nothing from the backup copy.
  5. Move CLAUDE.md guidance into AGENTS.md. Existing AGENTS.md files stay in place, and V2 discovers the global ~/.config/opencode/AGENTS.md and ambient AGENTS.md files. Copy the guidance from each CLAUDE.md the setup relied on into the applicable AGENTS.md, then confirm the CLAUDE.md file is no longer the only copy of any rule. A rule left only in CLAUDE.md is a rule V2 never reads.
  6. 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 with Plugin.define carrying a stable id, and move initialization into setup. In config, rename plugin to plugins and 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.
  7. Check the behaviour changes that have no config error. Three V2 changes take effect silently. Permissions are now one ordered permissions array: V1 grouped permission effects by tool, so bash becomes shell, task becomes subagent, and write/patch become edit — 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, because external_directory is 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.
  8. 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

What can go wrong

Limits

Related playbooks

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