Files
opencode-primer/docs/plugins.md
T
Wesam Abousaid a3f328c043 docs: refresh for OpenCode v1.17.13, add Go coverage, and rebrand
- Bump every version pin, pricing table, and model ID to the verified
  2026-07-05 state (v1.17.13): Claude Fable 5 / Sonnet 5 on Zen, new
  free tier, deprecation sunset table, v1.17.x changelog section
- Cover gaps: OpenCode Go vs Zen billing, Anthropic subscription-login
  removal (PR #18186), MCP resources, --mini mode, --auto flag, yolo mode
- Fix correctness bugs: command-template !`cmd` syntax in docs and
  .opencode/commands, protect-secrets regex missing 'cat .env', dual
  plugin exports, quickstart PATH fix, Playwright MCP flags, ctrl+d
  keybind conflict, agent/command required-field claims
- Fix links: cursor.com, windsurf.com, platform.claude.com,
  code.claude.com, opencode.ai/discord, Vercel Grep announcement
- Rebrand: banner (Images/banner.svg), 1280x640 social preview asset,
  hero redesign with star CTA, ecosystem stats, private vulnerability
  reporting channel, CI-matching local checks, MD060 lint opt-out
2026-07-05 14:11:51 +02:00

242 lines
8.2 KiB
Markdown

# 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 `husky` for 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:
```json
{
"$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:
```json
{
"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:
```bash
opencode plugin opencode-helicone-session
opencode plugin --global opencode-wakatime
```
## Plugin API
A plugin is an exported async function returning an object of **hooks** — named exports work fine, and every exported function in the file is loaded. There are two shapes: typed hooks like `tool.execute.before` that receive `(input, output)`, and a generic `event` handler that receives the lifecycle event stream:
```javascript
// .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 |
### Hooks and events
Two distinct shapes — don't confuse them. **Typed hooks** are top-level keys called with `(input, output)`; use them to inspect or mutate one operation (and `throw` to block it). The generic **`event`** handler receives a read-only lifecycle stream you match on `event.type`.
Verified against the [Plugins doc](https://opencode.ai/docs/plugins):
**Typed hooks** — `"hook.name": async (input, output) => { … }`:
| Hook | Fires | Key fields |
|---|---|---|
| `tool.execute.before` | Before a tool runs | `input.tool`; `output.args` (mutable) — `throw` to block |
| `tool.execute.after` | After a tool completes | `input.tool`, `input.args`; `output.title` / `output.output` |
| `shell.env` | Resolving shell environment | `input.cwd`; `output.env` (mutable) |
There's also a `tool` key for registering **custom tool definitions** from a plugin — the agent sees them alongside the built-in tools.
> 🆕 [v1.17.10](https://github.com/anomalyco/opencode/releases/tag/v1.17.10) added namespaced plugin hook APIs and a V2 plugin API supporting both Effect and Promise plugins.
**Event stream** — `event: async ({ event }) => { if (event.type === …) }`:
| Category | `event.type` values |
|---|---|
| **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` |
| **Todo** | `todo.updated` |
| **TUI** | `tui.prompt.append`, `tui.command.execute`, `tui.toast.show` |
| **Experimental** | `experimental.session.compacting` |
> 📚 Each hook/event carries its own payload. Full reference: [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).
## Common patterns
### 1. Auto-format on save
Every time the agent edits a file, run the project formatter:
```javascript
// .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.
```javascript
// .opencode/plugins/audit-log.js
import { appendFile } from "node:fs/promises";
export const AuditLog = async ({ directory }) => {
const logPath = `${directory}/.opencode/audit.jsonl`;
return {
"tool.execute.after": async (input, output) => {
await appendFile(
logPath,
JSON.stringify({
ts: new Date().toISOString(),
tool: input.tool,
title: output?.title,
}) + "\n"
);
},
};
};
```
### 3. Notify on long-running task completion
macOS notification when a session goes idle:
```javascript
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 edit to `.env` files or `secrets/` directories. `tool.execute.before` is a top-level hook — throwing aborts the call before it runs:
```javascript
export const ProtectSecrets = async () => {
return {
"tool.execute.before": async (input, output) => {
if (input.tool === "edit" || input.tool === "write") {
const path = output?.args?.filePath ?? "";
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):
1. NPM packages in the **global** `plugin` array
2. NPM packages in the **project** `plugin` array
3. **Global plugins** in `~/.config/opencode/plugins/`
4. **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.json` for transitive dependencies.
- Sandboxed plugins: run OpenCode in a container if you can't audit a plugin you need.
- Don't `eval` user-controlled strings in plugin code.
- Use absolute paths for shell commands so PATH manipulation can't redirect them.
## Debugging
```bash
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](https://opencode.ai/docs/plugins).
---
*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).*