---

name: writing-plugins description: Use when creating, editing, or reviewing OpenCode plugins. Covers plugin structure, event hooks, TypeScript typing, custom tools, dependency management, and common patterns like notifications and compaction hooks.

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

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

Or via npm in opencode.json:

Copy{
  "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

Copyimport 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

Copy// 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

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

Copy{
  "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

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

Tool Protection

Copyreturn {
  "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

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

Compaction Context

Copyreturn {
  "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