OpenCode 2.2: Desktop Plugins, Cache Controls and Breaking Changes

OpenCode 2.2 is available with experimental desktop plugins, new session-instruction controls and configurable prompt-cache lifetimes. Released on October 27, it also changes package imports and plugin requirements, and removes the published GitHub Action. Developers with custom integrations should check compatibility before upgrading.

This is separate from the earlier OpenCode 1.19 release, which gave V1 users an explicit route to V2. Version 2.2 changes the APIs and extension points that people already using V2 may depend on.

Check the breaking changes first

The 2.2 release notes identify three migrations that deserve attention.

The root of @opencode/ai now exports the Promise API. Effect users need @opencode/ai/effect, and the former @opencode/ai/promise path is removed. Projects importing these APIs should update imports and run their type checks before changing the installed version across a team.

The OpenCode GitHub Action is no longer published. The release asks users to remove it from workflows, so check repository automation as well as the local application.

TUI plugins now require OpenTUI 0.7. Plugins depending on 0.6 will not install until updated. Custom renderables also need lifecycle-hook changes, including moving hook assignments into constructors.

These are actionable compatibility changes. A desktop app opening successfully does not establish that a package integration or scheduled workflow still works.

Desktop plugins are experimental

The GUI plugin documentation describes extensions that add panels, commands, settings pages and native integrations. A package exposes its desktop code through ./gui-experimental, alongside any server or TUI parts.

Users install the package through the existing plugin mechanism. Desktop reads opencode.json(c), while TUI uses cli.json; a TUI-only configuration will therefore need attention when the same package adds a GUI component.

Plugin authors have two execution contexts. Window setup contributes interface elements, while the main entry runs in Electron's main process for native integrations. Keep code in the appropriate context rather than assuming the same modules work everywhere.

The API is explicitly experimental and may change between releases. For a team extension, pin the versions used in development and test the installed bundle in a clean setup, including disable and reload behaviour.

Session instructions can change without replacing the prompt

The plugin-context change exposes existing keyed session instructions to both Promise and Effect plugins. Extensions can create, inspect and remove entries, with updates announced at the next step boundary instead of queuing another model turn. The release notes also confirm that entries survive compaction and reverts.

That gives an extension a more specific way to keep session guidance current. A project tool could update a working constraint after configuration changes, for example, rather than repeatedly rebuilding a large instruction string. The extension still needs a clear rule for when an entry becomes stale and should be removed.

Cache lifetime comes with a cost-reporting caveat

The merged cache-control change adds settings.cache.ttl at provider, model and variant level. It accepts duration strings, with actual support depending on the provider and route. Leaving the setting unset preserves existing requests.

There is a documented limitation: when the provider does not return its own cost, OpenCode's estimate can undercount non-default cache writes because the catalog still has one cache-write price. Models routed through an AI SDK package ignore the setting.

A longer cache lifetime may help an agent that waits on slow tools, but the application needs to compare reuse against the provider's actual charges. Check provider usage records instead of treating OpenCode's displayed estimate as the final bill.

For an upgrade test, include one plugin-backed task and the automation that normally follows it. Verify imports, plugin loading and the resulting API usage. That will reveal more about readiness than a successful install alone.

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help technical founders explain developer-tool releases through practical migration guides and integration stories that developers can use and share.

Book a 30-minute call.