Files
opencode-primer/docs/plugins.md
T
Wesam Abousaid 9522c859fd docs(guides): add 10 deep-dive guides verified against opencode.ai/docs
- 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.
2026-05-18 19:59:28 +02:00

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 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:

{
  "$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):

  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

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.