OpenCode’s October 11, 2026 release adds explicit controls for moving to version 2 of the AI coding agent. For developers and software teams with customized setups, that makes this a useful moment to check compatibility—not an instruction to replace a working installation immediately. The new controls appear in the v1.19.0 release notes.
This is not V2’s launch day: the npm registry dates its 2.0.0 package to September 11. Neither the release notes nor the migration guide inspected on October 11 states a compulsory migration date or V1 retirement deadline. That absence is not a guarantee of future support.
Evaluate now, wait for a plugin, or plan a migration
The following choices are recommendations based on the documented compatibility boundaries, not certification that a particular setup will work.
Your setup | Suggested decision | What must be established |
|---|---|---|
No required plugins or custom integration | Consider a limited evaluation | Your essential workflow works with supported settings. |
A required third-party or local plugin | Wait if a compatible implementation is unavailable | The exact plugin release supports V2 and its required behavior survives the port. |
An application calling OpenCode’s server | Plan integration work before switching | Requests, responses and event handling match the new client contract. |
Keep configuration conversion separate
V2 reads supported V1 settings without rewriting them; native-format conversion is optional. Consider deferring conversion to keep the first evaluation focused. Preserve a V1 copy: configuration locations are shared, and V1 should not use V2-only files. See the configuration migration guidance.
Both versions use the opencode command. The migration guide says to remove package-managed V1 before installing V2; the curl installer replaces V1, rather than installing alongside it.
Check terminal preferences separately. V2 keeps them in one global ~/.config/opencode/cli.json file, or its XDG configuration-directory equivalent. There is no project-local CLI settings file, and terminal-only plugins belong in this separate configuration. See CLI settings.
A configuration change cannot port a plugin
V1 plugin code needs a V2 implementation; converting its configuration is not enough. OpenCode’s plugin migration guide describes a new @opencode/plugin entrypoint with a stable identifier and setup(ctx) to register behavior. Plugin users should confirm support for their exact package version; maintainers need to migrate the implementation, not merely rename its configuration entry.
The V2 command opencode plugin check looks for package updates. It is not a compatibility test, and local plugins and exact package revisions are skipped by update operations. Inventory terminal plugins as well as server plugins, then record the versions you intend to evaluate. See plugin management.
For a ported plugin, OpenCode recommends exercising its hooks, tools and subscriptions, checking cleanup after reload or removal, and testing the installed package. Those are verification steps for the reader, not tests performed for this article.
For the broader distinction between a portable package and consistent behavior, see RohitAI’s Agent Plugins 1.0 analysis. That specification is separate from OpenCode’s V2 plugin API.
Custom integrations need an architecture decision
If your application connects to an OpenCode server over HTTP, the documented package is @opencode/client. Local process management is provided separately through @opencode/client/service. By contrast, @opencode/sdk runs OpenCode inside your application, with requests handled in memory and no HTTP listener. Choosing the SDK is therefore an embedding decision, not simply an import replacement.
Event handling deserves its own check. The client documentation says subscriptions deliver live events only, without replay or automatic reconnection; a source failure ends existing subscriptions. An integration that tracks background work should establish how it resubscribes and reconciles state after interruption before relying on V2.
Check the guidance and diagnostics your workflow uses
Project instructions. V2 discovers
AGENTS.md, notCLAUDE.mdas a fallback. Itsinstructionssetting accepts file paths, patterns and URLs but does not currently load their contents into the model. Put required guidance in the appropriateAGENTS.mdand verify its scope. See instruction discovery.Code diagnostics. V2 accepts
lspsettings without running language servers or providing their tools and diagnostics. Workflows depending on those features need lint, type-check or compiler alternatives. See documented limitations.
The practical lesson is that a configuration file loading successfully does not prove the agent receives your instructions or performs the checks you expect. Evaluate the behavior that matters to the project, not just whether startup succeeds.
Make the switch only after the checks pass
For a pilot, write down the required tasks and expected results first. Confirm model access, permission behavior and required external tools; exercise the plugins and integrations the real work depends on. Record the exact versions used and leave unresolved requirements as blockers. A configuration backup alone should not be treated as a verified downgrade or session-history recovery procedure.
Once ready, the V1 release offers opencode upgrade --major and the terminal’s /update command for the move to V2. Its release notes also say that the V1 terminal no longer installs updates automatically; that statement should not be generalized to every V2 update setting.
The current V2 installation page lists Homebrew and npm options, plus standalone binaries for macOS, Windows and Linux. It says Windows package managers are unsupported. Use the instructions for your platform after establishing compatibility, rather than treating an available installer as evidence that your workflow is ready.
Reporting note: This AI-assisted guide draws on official release notes, npm metadata and OpenCode documentation checked on October 11, 2026. Recommendations are analysis of published contracts. No hands-on migration or performance testing was performed.