OpenCode Desktop Plugins: What They Are and How to Build One

OpenCode Desktop plugins are new in OpenCode v2.2.0, released on 27 October 2026, and they let you add your own panels, commands and settings pages to the OpenCode Desktop app. The release notes put it simply: you can now “create, install and share Desktop plugins” — marked experimental. Until now, OpenCode plugins could extend the server and the terminal interface. Now they can change the desktop app itself. I’ll explain it in plain English first, then walk through the developer steps from the official GUI plugin docs, and finish with the other plugin changes in v2.2.0 you should know about.

OpenCode Desktop plugins in plain English

OpenCode is an open-source AI coding agent you can run in the terminal or as a desktop app. Plugins let people add features to it without waiting for the OpenCode team. Before v2.2.0, a plugin could have two parts: a server part (the agent’s logic and tools) and a TUI part (the terminal interface).

v2.2.0 adds a third part for the desktop app. The docs say a GUI plugin “adds panels, commands, settings pages, and native integrations to OpenCode Desktop.” In practice that means a plugin can now:

• Add a command to the command palette (and optionally to the composer’s / menu).
• Add a panel or tab next to your session.
• Add its own settings page.
• Draw small bits of UI into slots, such as the session header or a strip at the bottom of the window.
• Add native menu items or embed a web view in the window.

The release notes also list new GUI plugin APIs for toasts, dialogs, notifications, tabs, composer controls and custom UI. And there’s a new place to manage them: Settings › Extensions › Plugins.

Experimental: what that means for you

If you’re a business owner, that means: try Desktop plugins, but don’t build anything you can’t afford to fix after an update. If you’re a developer, pin your OpenCode version while testing and re-check the docs on each release.

How an OpenCode Desktop plugin works: setup and main

A GUI plugin can run code in two places. The docs split them like this:

Most plugins only need setup. You reach for main when you need something native, like a menu bar item or a direct Node integration. One file serves both: the ./gui-experimental file default-exports Plugin.define, and both processes evaluate it. Window-only exports such as Command are undefined in the main process, so only use them inside setup.

Here’s the shape of the minimal example from the docs (a command that calls the plugin’s server part, plus a log line from main):

import { Command, Plugin } from "@opencode/plugin/gui"
import { Acme } from "./rpc"

export default Plugin.define({
  i18n: { en: { "command.open": "Open Acme" } },
  setup(ctx) {
    ctx.add(Command, () => ({
      id: "open",
      title: ctx.t("command.open"),
      run: () => void ctx.client.rpc(Acme).open({}),
    }))
  },
  main(ctx) {
    ctx.log.write("info", "acme started")
  },
})

Package setup: the ./gui-experimental export

A single npm package can ship server, TUI and GUI code. You add one ./gui-experimental export beside ./tui, and OpenCode Desktop loads it. This is the example package.json from the docs:

{
  "name": "opencode-acme-plugin",
  "type": "module",
  "exports": {
    ".": "./src/index.ts",
    "./tui": "./src/tui.tsx",
    "./gui-experimental": "./dist/gui-experimental.cjs"
  },
  "dependencies": { "@opencode/plugin": "latest" },
  "devDependencies": {
    "solid-js": "^1.9.0",
    "vite": "^7.0.0",
    "vite-plugin-solid": "^2.11.0"
  }
}

The GUI part doesn’t declare its own ID. It takes the plugin’s ID (the server part’s ID, or the package name if there’s no server part), and you read it as ctx.id. Tokens a plugin provides must use that ID as a prefix, like acme.counter.

Build it with the Vite preset

The ./gui-experimental file must be one prebuilt CommonJS file. The docs give you a Vite preset to make that:

// vite.config.ts
import { defineConfig } from "vite"
import { gui } from "@opencode/plugin/gui/vite"

export default defineConfig({ plugins: [gui()] })

Then run vite build. The preset compiles Solid JSX, emits one CommonJS file with every dynamic import() inlined (the app can’t load a second chunk), keeps the app’s shared modules, Electron and Node built-ins external, and bundles everything else.

Two options change the defaults:

• entry — the file that default-exports Plugin.define. Defaults to src/gui.tsx.
• outFile — the bundle your ./gui-experimental export points to. Defaults to dist/gui-experimental.cjs.

About shared modules: the app provides some modules to every plugin at runtime, including effect and @opencode/plugin/gui. The build fails if you import other effect/*, solid-js/* or @opencode/* paths, because a bundled copy wouldn’t share the app’s instance. The fix the docs give: import from the shared entry, e.g. import { Schema } from "effect".

Install and share OpenCode Desktop plugins

For users there’s nothing new to learn. The docs say users install a GUI plugin “like any other plugin; there is no separate GUI install step.” Add the package to your config:

// opencode.jsonc
{
  "plugins": ["opencode-acme-plugin"],
}

Plugin options go in the same entry, e.g. { "package": "opencode-acme-plugin", "options": { "team": "core" } }. The GUI part reads them as ctx.options — the same values the server part gets — and changing them reloads the plugin.

Sharing works the same way as other OpenCode plugins: because server, TUI and GUI code can ship from one npm package, the package is what you share. Anyone who adds its name to "plugins" gets all the parts it contains. Once installed, you can manage Desktop plugins from Settings › Extensions › Plugins.

Other OpenCode v2.2.0 plugin changes

Desktop plugins are the headline, but the v2.2.0 release changes several other things plugin authors should know:

• Session instructions: plugins can attach and update keyed session instructions with ctx.session.instructions.entry.put/list/remove. Each change is added as a small update at the next step instead of editing the system prompt, so the prompt cache isn’t busted. Entries survive compaction and reverts and don’t start an extra model turn.
• Image and decision generation: new experimental APIs for plugins and the SDK, for image generation or decision-model workflows.
• Prompt cache TTLs: now configurable per provider and model.
• Todo tool: restored in desktop as an opt-in.

And three breaking changes:

• @opencode/ai root is now the Promise API. The Effect API moved to @opencode/ai/effect, and @opencode/ai/promise is removed.
• The OpenCode GitHub Action is removed. It’s no longer published; remove it from your workflows.
• TUI plugins require OpenTUI 0.7. @opencode/plugin now needs @opentui/core and @opentui/solid 0.7.0. Plugins on OpenTUI 0.6 fail to install until they upgrade.

OpenCode vs Hermes: where Desktop plugins fit

I run OpenCode next to Hermes in my own setup. OpenCode is focused on coding; Hermes is a general agent you can reach from chat apps. Desktop plugins make OpenCode’s app much more customisable for teams that live in it all day. For a full comparison, read Hermes Agent vs OpenCode, and if you want free models in either, see Hermes OpenCode Zen.

My verdict on OpenCode Desktop plugins

This is a big step for OpenCode. One package can now change the server, the terminal and the desktop app, and users install it with one line in their config. The experimental label is real, so build small and expect changes. If you or your team already use OpenCode every day, OpenCode Desktop plugins are the easiest way yet to make the app fit how you work.

About Julian Goldie

I’m Julian Goldie — founder of Goldie Agency and the AI Profit Boardroom. I test new AI agents almost every day for 432K+ YouTube subscribers and run Hermes, OpenClaw, OpenCode, Claude and Codex side by side in my own Agent OS. Claim your free strategy session or join the AI Profit Boardroom.

Want another angle? Read the AI Profit Boardroom guide to OpenCode Desktop Plugins.

FAQ: opencode desktop plugins

What are OpenCode Desktop plugins?

They’re plugins that add panels, commands, settings pages and native integrations to the OpenCode Desktop app. They arrived in OpenCode v2.2.0 on 27 October 2026 and are marked experimental.

How do I install an OpenCode Desktop plugin?

Add the package name to “plugins” in opencode.jsonc, for example “plugins”: [“opencode-acme-plugin”]. There is no separate GUI install step.

What SDK do OpenCode GUI plugins use?

The GUI plugin SDK, @opencode/plugin/gui. Your package exposes a ./gui-experimental export pointing to one prebuilt CommonJS file, built with the Vite preset from @opencode/plugin/gui/vite.

What is the difference between setup and main?

setup runs in every desktop window and adds panels, commands, settings pages, slots and more. main runs once in the Electron main process for Ipc contracts, native menus, web view embeds and Node or Electron integrations.

Are OpenCode Desktop plugins stable?

Not yet. The docs say the GUI plugin API is experimental and may change between releases, so test carefully and re-check the docs after each update.

Related reading

• Hermes Agent vs OpenCode
• Hermes OpenCode Zen
• GLM-5.3 Flash in OpenCode

Last updated October 2026. This page is a living guide to opencode desktop plugins — the facts here move fast and it is updated as they do.