- quickstart.md: 5-minute path from curl to first commit - zen.md: model gateway with full lineup, pricing, BYOK, patterns - tui.md: keybinds, leader chords, themes, customization, sessions - agents.md: custom agents and subagents, full frontmatter, permission map - commands.md: custom slash commands, placeholders, patterns, override rules - skills.md: discoverable workflows, SKILL.md format, description-as-trigger - plugins.md: lifecycle hooks, full event catalog, four real patterns - mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers, with mermaid N×M → N+M diagram - migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does better" subsections so the comparisons aren't one-sided - workflows.md: seven real recipes (TDD, bug investigation, multi-agent review, cross-repo research, migrations, CI, visual iteration) — CI example shows GitHub Actions + GitLab CI to avoid platform bias Every model slug, permission key, config key, env var, and CLI flag verified against the JSON schema or the live docs site.
6.8 KiB
Plugins
Mental model: Plugins are OpenCode's event-driven extension surface — small JavaScript or TypeScript modules that subscribe to lifecycle events (tool calls, file edits, session state) and run code automatically. Think
huskyfor your AI session.
When to write a plugin
| Reach for a plugin when… | Skip plugins and use a command/skill if… |
|---|---|
| You want code to run automatically (no user prompt) | The trigger is "user types /something" |
| You're connecting to an external system (notifications, logging, telemetry) | You're shaping the prompt or output |
| You want to enforce policy (block writes to certain paths) | You want the agent to decide what to do |
Where plugins live
Three locations:
| Location | Scope |
|---|---|
.opencode/plugins/<name>.{js,ts} |
Project |
~/.config/opencode/plugins/<name>.{js,ts} |
Global |
plugin: [...] in opencode.json |
NPM packages |
NPM-installed plugins:
{
"$schema": "https://opencode.ai/config.json",
"plugin": [
"opencode-helicone-session",
"opencode-wakatime",
"@my-org/custom-plugin"
]
}
These install on first run via Bun and cache under ~/.cache/opencode/node_modules/.
Dependencies for local plugins
Local plugins can use npm packages. Drop a package.json next to them:
{
"dependencies": {
"shescape": "^2.1.0",
"node-notifier": "^10.0.1"
}
}
Run opencode plugin <module> (or opencode plug) to add a plugin and let OpenCode update your config:
opencode plugin opencode-helicone-session
opencode plugin --global opencode-wakatime
Plugin API
A plugin is a default-export async function returning an object of event handlers:
// .opencode/plugins/notify-on-idle.js
export const NotifyOnIdle = async ({ project, client, $, directory, worktree }) => {
return {
event: async ({ event }) => {
if (event.type === "session.idle") {
await $`osascript -e 'display notification "Session done!" with title "opencode"'`;
}
},
};
};
Arguments
| Argument | What you get |
|---|---|
project |
Project metadata — name, root, language hints |
directory |
Current working directory string |
worktree |
Git worktree path (when applicable) |
client |
OpenCode SDK client — call back into OpenCode from inside the plugin |
$ |
Bun shell — run commands; supports tagged-template syntax |
Available events
Verified against the Plugins doc:
| Category | Events |
|---|---|
| Tools | tool.execute.before, tool.execute.after |
| Files | file.edited, file.watcher.updated |
| Sessions | session.created, session.updated, session.compacted, session.idle, session.status, session.error, session.diff, session.deleted |
| Messages | message.updated, message.removed, message.part.updated, message.part.removed |
| Commands | command.executed |
| Permissions | permission.asked, permission.replied |
| LSP | lsp.client.diagnostics, lsp.updated |
| Server / installation | server.connected, installation.updated |
| Shell | shell.env |
| Todo | todo.updated |
| TUI | tui.prompt.append, tui.command.execute, tui.toast.show |
📚 Each event carries event-specific payload. Full reference: opencode.ai/docs/plugins.
Common patterns
1. Auto-format on save
Every time the agent edits a file, run the project formatter:
// .opencode/plugins/autoformat.js
export const Autoformat = async ({ $ }) => {
return {
event: async ({ event }) => {
if (event.type === "file.edited") {
const path = event.path;
if (/\.(ts|tsx|js|jsx|json|md)$/.test(path)) {
await $`pnpm prettier --write ${path}`.quiet();
} else if (/\.py$/.test(path)) {
await $`ruff format ${path}`.quiet();
} else if (/\.go$/.test(path)) {
await $`gofmt -w ${path}`.quiet();
}
}
},
};
};
2. Action audit log
Append every tool call to a JSONL log — paper trail for what the agent did.
// .opencode/plugins/audit-log.js
import { appendFile } from "node:fs/promises";
export const AuditLog = async ({ directory }) => {
const logPath = `${directory}/.opencode/audit.jsonl`;
return {
event: async ({ event }) => {
if (event.type === "tool.execute.after") {
await appendFile(
logPath,
JSON.stringify({
ts: new Date().toISOString(),
tool: event.tool,
input: event.input,
success: !event.error,
}) + "\n"
);
}
},
};
};
3. Notify on long-running task completion
macOS notification when a session goes idle:
export const NotifyOnIdle = async ({ $ }) => {
return {
event: async ({ event }) => {
if (event.type === "session.idle") {
await $`osascript -e 'display notification "OpenCode is idle" with title "opencode" sound name "Glass"'`.quiet();
}
},
};
};
4. Block sensitive paths
Prevent any edits to .env files or secrets/ directories:
export const ProtectSecrets = async ({ client }) => {
return {
event: async ({ event }) => {
if (event.type === "tool.execute.before" && event.tool === "edit") {
const path = event.input?.path ?? "";
if (/\.env|secrets\//i.test(path)) {
throw new Error(`Plugin blocked: ${path} is a protected path`);
}
}
},
};
};
Loading order
Plugins load in this order (later ones can override earlier behavior):
- NPM packages in the global
pluginarray - NPM packages in the project
pluginarray - Global plugins in
~/.config/opencode/plugins/ - Project plugins in
.opencode/plugins/
Security
⚠️ Plugins run with your user permissions. They can read, modify, delete any file you can, plus make network calls. Treat installation like running an unaudited shell script — read every third-party plugin before adding it.
Best practices:
- Pin plugin versions in
opencode.json("opencode-foo@1.2.3"). - Audit
package.jsonfor transitive dependencies. - Sandboxed plugins: run OpenCode in a container if you can't audit a plugin you need.
- Don't
evaluser-controlled strings in plugin code. - Use absolute paths for shell commands so PATH manipulation can't redirect them.
Debugging
opencode --log-level DEBUG --print-logs # see plugin loading
opencode debug # debug subcommands
Plugin errors show up in the TUI; full traces appear in OpenCode's log (default at ~/.local/share/opencode/log/, or stderr with --print-logs).
📚 Full Plugins guide and event reference: opencode.ai/docs/plugins.