OpenCode desktop plugins landed in OpenCode v2.2.0 on 27 October 2026: you can now create, install and share plugins that add panels, commands, settings pages and native integrations to the OpenCode Desktop app. It's marked experimental, but it works today, and installing one is the same as installing any other OpenCode plugin.
📺 Watch: OpenCode Desktop Just Got WAY More Useful
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
Here's what they are, how to install them, how to build your own, and the new plugin APIs that came in the same release.
What OpenCode desktop plugins actually are
An OpenCode plugin is one npm package that can carry up to four parts. The docs list them like this:
- Server part. Runs in the OpenCode server and adds tools, hooks, integrations, commands and agents.
- TUI part. Adds commands, routes and slots to the terminal UI.
- GUI part. The new one. It's the ./gui-experimental export, and it adds panels, commands, settings pages and native integrations to OpenCode Desktop.
- RPC part. A typed contract the server part implements and the other parts call.
So a "desktop plugin" is really any plugin that ships that GUI part. It can live alone or sit beside a server and TUI part in the same package. The name has "experimental" baked into the export on purpose: the docs say the GUI plugin API may change between releases.
The GUI part runs in two places. Its setup code runs in every desktop window and adds panels, commands, settings pages, slots, link handlers and styles. Its main code runs once in the Electron main process, for native menu items, embedded web views and Node or Electron integrations.
If you want to get properly good at agent coding tools like this, the AI Profit Boardroom ($69/mo) gives you the Agent OS, a 30-day AI agent roadmap, daily tutorials as new tools drop, 4 coaching calls a week and the prompt library, with 3,400+ members.
📺 Watch: NEW Hermes Desktop Browser Update Is INSANE!
How to install OpenCode desktop plugins
There's no separate GUI install step. You install the plugin, and if it has a GUI part, Desktop picks it up.
- Add it with the CLI. The docs give opencode plugin add with an npm name and optional version, for example opencode plugin add opencode-acme-plugin@1.2.0. Git sources work too, such as opencode plugin add github:acme/opencode-plugin.
- Or add it to your config. List the package in the plugins array of your global opencode.json or opencode.jsonc, which lives at ~/.config/opencode/.
- Check it in the app. Open Settings, Extensions, Plugins. Your plugins appear there when the app's own server is selected.
One thing trips people up. The desktop app reads plugins only from opencode.json(c). The TUI reads its own plugins from cli.json. So if a plugin used to be TUI-only and sits in cli.json, it also needs to go in opencode.json(c) once it adds a GUI part. And put it in the global config if you want it in every window.
Managing them afterwards, all from the docs:
- opencode plugin list shows what's installed.
- opencode plugin check looks for updates, including GUI-only packages.
- opencode plugin update updates everything outdated, or name one package.
- opencode plugin remove plus the package name takes it out.
In Settings, Extensions, Plugins, each plugin has a switch. That switch turns off only its desktop UI. To turn off the whole plugin, add a minus sign and its id to your plugins list. There's also a Reload button for when a GUI fails to load.
Planning which tools your team should standardise on? Book a free AI strategy session.
📺 Watch: Omniroute + OpenCode: 100% FREE AI Coding Setup!
How to create a desktop plugin
Here's the build path from the GUI plugin docs, in plain steps.
1. Add the export to your package
In package.json, add a ./gui-experimental export pointing at your built file. The default is dist/gui-experimental.cjs. Keep @opencode/plugin as a dependency. The GUI takes the plugin's id from the server part, or from the package name if there's no server part.
2. Write the entry file
The entry, src/gui.tsx by default, default-exports Plugin.define from @opencode/plugin/gui. Inside it you write setup for window code (Solid components, commands, panels) and main for Electron main-process code. Both processes load the whole file, and each gets inert placeholders for the other side's modules, so keep each side's code inside its own function.
3. Build one CommonJS file
The GUI must be a single prebuilt CommonJS file. OpenCode ships a Vite preset for it at @opencode/plugin/gui/vite. Add the dev tools with bun add -d vite vite-plugin-solid solid-js, then run vite build. The preset compiles Solid, inlines dynamic imports and fails the build if you bundle a module the app already provides.
4. Develop with live reload
Point your config at the local plugin folder and run vite build --watch. Per the docs, each rebuild reloads the plugin's GUI in every window and the main process, without restarting the server part.
5. Share it
To share, publish it to npm with npm publish. Build the GUI bundle first and include it in your package files. The docs also say to test the installed package, not just a linked copy.
Two rules to know. A plugin whose server part fails to load gets no GUI. And ids in the opencode namespace, or ones that clash with the app's own plugins, are reserved, so the GUI won't load.
New plugin APIs in OpenCode 2.2
Desktop plugins got the headline, but the release notes add two more things plugin builders should know.
| Feature | What it does | Status |
|---|---|---|
| Desktop GUI plugins | Panels, commands, settings pages and native integrations in OpenCode Desktop | Experimental |
| Image and decision generation | Image generation or decision-model workflows from plugins and the SDK | Experimental |
| Keyed session instructions | Attach, list and remove named instruction entries for a session | New in 2.2 |
| Settings, Extensions, Plugins | Manage desktop plugins inside the app | New in 2.2 |
Image and decision generation
The release notes say plugins and the SDK get experimental image and decision generation APIs, for image generation or decision-model workflows. In the AI package, Decision APIs replace the old experimental evaluations, including OpenAI Decisions, System One and Cloudflare Run models.
Keyed session instructions
This one is clever. Plugins can now attach and update named instruction entries with ctx.session.instructions.entry.put, list and remove. Instead of editing the system prompt and busting the prompt cache, each change is added as a small update at the next step.
Per the notes, these entries survive compaction and reverts, and they don't start an extra model turn. The server docs show them rendering as context blocks with a key, like a deploy-target entry set to production. Great for plugins that track state the model needs to keep seeing.
The experimental caveats
Go in with eyes open:
- The API can change. The docs say so directly, and the export name carries the warning.
- TUI plugins need OpenTUI 0.7. A breaking change in 2.2: plugins built on OpenTUI 0.6 fail to install until they upgrade.
- Pin your versions. The docs advise using plugin versions compatible with the OpenCode release you target.
- No official directory yet. OpenCode doesn't publish a list of desktop plugins yet, so check each package's source before you add it.
Comparing OpenCode with other agents? My Hermes Agent vs OpenCode breakdown covers where each one wins. To pick the model behind it, see Goldie Bench, and the Agent OS guide shows how I run several agents side by side. Want help choosing? Get a free AI strategy session.
FAQ
Which OpenCode version has desktop plugins?
OpenCode v2.2.0, released on GitHub on 27 October 2026. The feature is labelled experimental.
Do desktop plugins need a separate install?
No. You install the plugin once with opencode plugin add or your config file. If it ships a GUI part, OpenCode Desktop loads it.
What are the best OpenCode desktop plugins?
The feature is days old and there's no official list yet. Watch the OpenCode docs and release notes, and check any package's source before installing.
Can I turn off a plugin's desktop UI but keep the rest?
Yes. The switch in Settings, Extensions, Plugins turns off only the desktop UI. Add a minus sign before the plugin id in your config to disable all of it.
Ready to build with OpenCode desktop plugins? Join the AI Profit Boardroom for daily AI agent tutorials, or book a free AI strategy session and we'll plan your stack.
