Writing OpenCode Plugins
Use this skill to implement production-quality OpenCode plugins. Treat the repository's exported types and runtime as authoritative because plugin APIs are evolving and public docs may lag.
Start Here
- Decide which runtime owns the feature.
- Read the relevant public type before writing code.
- Find one focused in-repository example using the same API.
- Implement the smallest target-specific module.
- Test loading, behavior, failure, and cleanup in the owning package.
| Need |
Plugin target |
Import |
Configuration |
| Hooks, tools, auth, providers, model parameters, shell environment |
Server |
@opencode-ai/plugin |
opencode.json or auto-discovered .opencode/plugins/*.{ts,js} |
| Commands, keybindings, routes, dialogs, slots, themes, notifications |
TUI |
@opencode-ai/plugin/tui |
Explicit tui.json plugin entry |
| Both |
Two target-only entrypoints |
Both imports in separate files |
Package exports ./server and ./tui |
Never export server and tui from the same module. Do not use server event hooks as a substitute for interactive TUI APIs.
Verify The Current Contract
Read these files before implementing unfamiliar behavior:
packages/plugin/src/index.ts: authoritative server plugin and hook types.
packages/plugin/src/tool.ts: custom tool schema, context, permission, metadata, attachments, and result types.
packages/plugin/src/tui.ts: authoritative TUI API and module types.
packages/opencode/specs/tui-plugins.md: TUI loading, packaging, lifecycle, and API semantics.
packages/opencode/src/plugin/shared.ts: target validation, IDs, and entrypoint resolution.
packages/opencode/src/plugin/loader.ts: install, compatibility, and import behavior.
If these disagree with examples or website docs, follow exported types and runtime behavior, then update stale documentation when appropriate.
Choose A Module Shape
Prefer the explicit module object for new server plugins:
import type { Plugin, PluginModule } from '@opencode-ai/plugin';
const server: Plugin = async ({ client, directory }, options) => ({
dispose: async () => {},
});
export default {
id: 'acme.example',
server,
} satisfies PluginModule & { id: string };
Legacy server-only local plugins may export a plugin function directly. In a legacy module every distinct named export is interpreted as a plugin, so do not export unrelated constants. Prefer a default module object for new code.
TUI plugins always use a default module object:
/** @jsxImportSource @opentui/solid */
import type { TuiPlugin, TuiPluginModule } from '@opencode-ai/plugin/tui';
const tui: TuiPlugin = async (api) => {
api.ui.toast({ message: 'Plugin loaded' });
};
export default {
id: 'acme.example-tui',
tui,
} satisfies TuiPluginModule & { id: string };
File plugins require a stable, non-empty id. npm plugins may derive the ID from the package name, but an explicit namespaced ID makes state, diagnostics, and collision handling clearer.
Engineering Rules
- Use TypeScript and
satisfies against the public plugin type.
- Parse and validate
options; they arrive as unvalidated Record<string, unknown>.
- Namespace plugin IDs, command IDs, route names, modes, slot names, and shared KV keys.
- Use the directory supplied by the plugin or tool context, not
process.cwd().
- Honor
AbortSignal for long-running or cancellable work.
- Use
client.app.log() for structured server logging instead of console.log.
- Request permission before sensitive or consequential custom-tool work.
- Keep notifications privacy-safe; do not expose prompts, secrets, paths, commands, or raw errors.
- Register only needed hooks and UI resources. Avoid broad event subscriptions when a specific hook exists.
- Make cleanup bounded, idempotent, and safe after partial initialization.
- Do not depend on undocumented load order to resolve ownership conflicts.
Testing Workflow
Server plugin tests belong under packages/opencode/test/plugin/ or the closest owning subsystem. TUI runtime tests belong under packages/opencode/test/cli/tui/; component-level TUI tests may belong in packages/tui.
Test at least:
- valid loading and target/entrypoint selection;
- configured options and malformed options;
- the observable behavior, not a duplicate of implementation logic;
- abort, failure, and partial-initialization behavior;
- cleanup or disposal;
- duplicate IDs or registrations when relevant;
- local file and npm packaging behavior when publishing.
Run tests from the package directory, never the repository root. Use bun typecheck from the owning package for type checking.
Review Checklist
- The feature is in the correct server or TUI runtime.
- Module shape and import path match the target.
- Server and TUI entrypoints are separate.
- IDs and persistent keys are stable and namespaced.
- Options and external data are validated.
- Hook output mutation preserves other plugins' changes.
- Tools use context directory, permission, metadata, and abort correctly.
- TUI keybindings are mode-gated unless intentionally global.
- TUI resources and custom side effects are disposed.
- Package exports,
engines.opencode, and config target are correct.
- Tests cover behavior and lifecycle.
References
- Server plugins: hooks, custom tools, lifecycle, and examples.
- TUI plugins: keymaps, routes, dialogs, slots, state, and lifecycle.
- Packaging and testing: config, package exports, compatibility, and test locations.
1---2name: writing-opencode-plugins3description: OpenCode plugins, @opencode-ai/plugin, @opencode-ai/plugin/tui, plugin hooks, custom tools, TUI routes, slots, keymaps, and packaging. Use when creating, editing, reviewing, testing, or publishing server or TUI plugins for OpenCode.4metadata:5 source: https://skillmd.com/skills/sveltejs/writing-opencode-plugins6 internal: true7---89# Writing OpenCode Plugins1011Use this skill to implement production-quality OpenCode plugins. Treat the repository's exported types and runtime as authoritative because plugin APIs are evolving and public docs may lag.1213## Start Here14151. Decide which runtime owns the feature.162. Read the relevant public type before writing code.173. Find one focused in-repository example using the same API.184. Implement the smallest target-specific module.195. Test loading, behavior, failure, and cleanup in the owning package.2021| Need | Plugin target | Import | Configuration |22| -------------------------------------------------------------------- | --------------------------- | ------------------------------ | ---------------------------------------------------------------- |23| Hooks, tools, auth, providers, model parameters, shell environment | Server | `@opencode-ai/plugin` | `opencode.json` or auto-discovered `.opencode/plugins/*.{ts,js}` |24| Commands, keybindings, routes, dialogs, slots, themes, notifications | TUI | `@opencode-ai/plugin/tui` | Explicit `tui.json` `plugin` entry |25| Both | Two target-only entrypoints | Both imports in separate files | Package exports `./server` and `./tui` |2627Never export `server` and `tui` from the same module. Do not use server event hooks as a substitute for interactive TUI APIs.2829## Verify The Current Contract3031Read these files before implementing unfamiliar behavior:3233- `packages/plugin/src/index.ts`: authoritative server plugin and hook types.34- `packages/plugin/src/tool.ts`: custom tool schema, context, permission, metadata, attachments, and result types.35- `packages/plugin/src/tui.ts`: authoritative TUI API and module types.36- `packages/opencode/specs/tui-plugins.md`: TUI loading, packaging, lifecycle, and API semantics.37- `packages/opencode/src/plugin/shared.ts`: target validation, IDs, and entrypoint resolution.38- `packages/opencode/src/plugin/loader.ts`: install, compatibility, and import behavior.3940If these disagree with examples or website docs, follow exported types and runtime behavior, then update stale documentation when appropriate.4142## Choose A Module Shape4344Prefer the explicit module object for new server plugins:4546```ts47import type { Plugin, PluginModule } from '@opencode-ai/plugin';4849const server: Plugin = async ({ client, directory }, options) => ({50 dispose: async () => {},51});5253export default {54 id: 'acme.example',55 server,56} satisfies PluginModule & { id: string };57```5859Legacy server-only local plugins may export a plugin function directly. In a legacy module every distinct named export is interpreted as a plugin, so do not export unrelated constants. Prefer a default module object for new code.6061TUI plugins always use a default module object:6263```tsx64/** @jsxImportSource @opentui/solid */65import type { TuiPlugin, TuiPluginModule } from '@opencode-ai/plugin/tui';6667const tui: TuiPlugin = async (api) => {68 api.ui.toast({ message: 'Plugin loaded' });69};7071export default {72 id: 'acme.example-tui',73 tui,74} satisfies TuiPluginModule & { id: string };75```7677File plugins require a stable, non-empty `id`. npm plugins may derive the ID from the package name, but an explicit namespaced ID makes state, diagnostics, and collision handling clearer.7879## Engineering Rules8081- Use TypeScript and `satisfies` against the public plugin type.82- Parse and validate `options`; they arrive as unvalidated `Record<string, unknown>`.83- Namespace plugin IDs, command IDs, route names, modes, slot names, and shared KV keys.84- Use the directory supplied by the plugin or tool context, not `process.cwd()`.85- Honor `AbortSignal` for long-running or cancellable work.86- Use `client.app.log()` for structured server logging instead of `console.log`.87- Request permission before sensitive or consequential custom-tool work.88- Keep notifications privacy-safe; do not expose prompts, secrets, paths, commands, or raw errors.89- Register only needed hooks and UI resources. Avoid broad event subscriptions when a specific hook exists.90- Make cleanup bounded, idempotent, and safe after partial initialization.91- Do not depend on undocumented load order to resolve ownership conflicts.9293## Testing Workflow9495Server plugin tests belong under `packages/opencode/test/plugin/` or the closest owning subsystem. TUI runtime tests belong under `packages/opencode/test/cli/tui/`; component-level TUI tests may belong in `packages/tui`.9697Test at least:9899- valid loading and target/entrypoint selection;100- configured options and malformed options;101- the observable behavior, not a duplicate of implementation logic;102- abort, failure, and partial-initialization behavior;103- cleanup or disposal;104- duplicate IDs or registrations when relevant;105- local file and npm packaging behavior when publishing.106107Run tests from the package directory, never the repository root. Use `bun typecheck` from the owning package for type checking.108109## Review Checklist110111- The feature is in the correct server or TUI runtime.112- Module shape and import path match the target.113- Server and TUI entrypoints are separate.114- IDs and persistent keys are stable and namespaced.115- Options and external data are validated.116- Hook output mutation preserves other plugins' changes.117- Tools use context directory, permission, metadata, and abort correctly.118- TUI keybindings are mode-gated unless intentionally global.119- TUI resources and custom side effects are disposed.120- Package exports, `engines.opencode`, and config target are correct.121- Tests cover behavior and lifecycle.122123## References124125- [Server plugins](references/server-plugins.md): hooks, custom tools, lifecycle, and examples.126- [TUI plugins](references/tui-plugins.md): keymaps, routes, dialogs, slots, state, and lifecycle.127- [Packaging and testing](references/packaging-testing.md): config, package exports, compatibility, and test locations.