A starting point for an opencode v2 plugin with all four parts: server, TUI, GUI (OpenCode Desktop, experimental) and RPC. Each part implements one or two small examples and lists every other area it can extend as commented-out code. Uncomment what you need and delete the rest.
-
Click Use this template on GitHub (or clone and re-init git).
-
Rename the plugin:
package.jsonname(also the import path other plugins use for<name>/rpc)PLUGIN_IDinsrc/shared/constants.ts(server id, TUI id prefix, tool namespace, RPC id)- the example agent (
agents/example.md) and skill (skills/example/), plus their ids insrc/server/agents.tsandsrc/server/skills.ts - the
examplereference (references/example-docs/, registered insrc/server/references.ts)
-
Install and check:
bun install bun run typecheck bun test bun run build # GUI bundle -> dist/gui-experimental.cjs
-
Pin
@opencode/plugininpackage.jsonto youropencode --version.
Add the checkout to plugins in opencode.json(c) (global or project):
With options for the server part (ctx.options). The example reads one:
node, the command that runs mcp/hello_mcp.js (default node; bun or
a full path also work):
{
"plugins": [{ "package": "<path-to-this-checkout>", "options": { "node": "bun" } }]
}One entry loads every part: the TUI loads the TUI parts of the plugins its
server loads, and OpenCode Desktop loads GUI parts from the global config.
Run bun run build (or bun run build:watch) before Desktop can show the
GUI part; the other parts run from source.
What the examples do once loaded:
| Part | Example | Try it |
|---|---|---|
| Server | example agent, example skill, hello tool, example reference, hello-mcp MCP server, RPC handler |
pick the agent; ask for the example skill, the hello tool or the MCP hello tool; attach the example reference and ask about chapter 1 |
| TUI | palette + /plugin-ping command |
shows the server's RPC answer as a toast |
| GUI | "Ping the plugin's server part" palette command | shows the answer in a dialog |
| RPC | ping method |
called by the TUI and GUI examples |
package.json exports: one key per part (".", "./server", "./tui", "./gui-experimental", "./rpc")
vite.config.ts GUI build (the only part that needs one)
agents/ one agent per .md file (frontmatter + system prompt)
skills/ one skill per folder (SKILL.md)
references/ one directory per reference (example-docs/ is the "example" reference; attach it by alias)
mcp/ MCP servers the plugin ships (hello_mcp.js: stdio, no dependencies)
src/server/ server part: server.ts wires one file per domain
src/tui/ TUI part: tui.tsx wires one file per area
src/gui/ GUI part: gui.tsx wires one file per registry
src/rpc/ RPC contract shared by every part and outside callers
src/shared/ code more than one part imports
tests/ bun test
AGENTS.md describes the conventions for coding agents working in a plugin
made from this template.
V1 support is included as an example. Target V2 first: build features on the V2 API, and add V1 hooks only where they extend compatibility to opencode 1.x users. Nothing in V1 should drive the design.
The server entry also works on opencode 1.x (1.18.29 or later). Its default export is one object with both entry points:
setup()(fromPlugin.define): what V2 runs.server()(src/server/v1.ts): what V1 runs. It returns V1 hooks; the example'sconfighook adds the same agent and MCP server, reusing the loaders the V2 code calls.
V1 loads the plugin with "plugin" (singular) in opencode.json:
{ "plugin": ["file://<path-to-this-checkout>"] }. Targeting V2 only?
Delete v1.ts, its import and the server: v1Server line, and export
Plugin.define(...) directly.
- TUI (OpenTUI + Solid): add
@opentui/core,@opentui/solidandsolid-jstodevDependenciesand topeerDependencies.src/tui/tui.tsxalready carries the@jsxImportSource @opentui/solidpragma. - GUI (Solid in Electron):
solid-jsis already a dev dependency; import only modules the desktop app provides (see the GUI docs, "Shared modules").
Build the GUI first (dist/ is in files), then npm publish. Users then
list the package name in plugins instead of a path.
{ "plugins": ["<path-to-this-checkout>"] }