writing-plugins（编写插件）

Writing Plugins

Overview

Plugins extend OpenCode by hooking into events and customizing behavior. They're JavaScript/TypeScript modules that export functions receiving a context object and returning hooks.

When to Use

• Creating event-driven automation (notifications, logging, protection)
• Adding custom tools to OpenCode
• Modifying tool behavior before/after execution
• Customizing session compaction behavior
• Integrating with external services

Don't use for: simple prompts (use commands), static configuration (use config), or agent behavior (use agents).

File Locations

.opencode/plugin/<name>.js|ts       # Project-local
~/.config/opencode/plugin/<name>.js|ts  # Global/personal

Or via npm in opencode.json:

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Load Order

1. Global config (~/.config/opencode/opencode.json)
2. Project config (opencode.json)
3. Global plugin directory (~/.config/opencode/plugin/)
4. Project plugin directory (.opencode/plugin/)

Basic Structure

import type { Plugin } from "@opencode-ai/plugin";

export const MyPlugin: Plugin = async ({
  project,
  client,
  $,
  directory,
  worktree,
}) => {
  // Initialization code here

  return {
    // Hook implementations
  };
};

Context Object

Event Hooks

Event Categories

Hook Patterns

// Event subscription
return {
  event: async ({ event }) => {
    if (event.type === "session.idle") {
      // Handle event
    }
  },
};

// Tool interception
return {
  "tool.execute.before": async (input, output) => {
    // Modify or block tool execution
  },
  "tool.execute.after": async (input, output) => {
    // React to tool completion
  },
};

Custom Tools

import { type Plugin, tool } from "@opencode-ai/plugin";

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, ctx) {
          return `Hello ${args.foo}!`;
        },
      }),
    },
  };
};

Dependencies

Add external packages via .opencode/package.json:

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

OpenCode runs bun install at startup. npm plugins are cached in ~/.cache/opencode/node_modules/.

Quick Reference

Common Patterns

Notification on Completion

return {
  event: async ({ event }) => {
    if (event.type === "session.idle") {
      await $`osascript -e 'display notification "Done!" with title "opencode"'`;
    }
  },
};

Tool Protection

return {
  "tool.execute.before": async (input, output) => {
    if (input.tool === "read" && output.args.filePath.includes(".env")) {
      throw new Error("Do not read .env files");
    }
  },
};

Structured Logging

await client.app.log({
  service: "my-plugin",
  level: "info", // debug, info, warn, error
  message: "Plugin initialized",
  extra: { foo: "bar" },
});

Compaction Context

return {
  "experimental.session.compacting": async (input, output) => {
    // Add context (appended to default prompt)
    output.context.push(`## Custom Context\n...`);

    // OR replace entire prompt
    output.prompt = `Your custom compaction prompt...`;
  },
};

Common Mistakes

Validation Checklist

• [ ] Plugin exports named function (not default)
• [ ] Function is async and returns hooks object
• [ ] TypeScript uses Plugin type import
• [ ] Event types checked before handling
• [ ] External deps listed in package.json
• [ ] Uses client.app.log() not console.log
• [ ] Tool definitions have description and args schema