OpenCode's plugin system is what separates it from every other AI coding tool. While Claude Code and Cursor offer limited extensibility, OpenCode lets you hook into 25+ lifecycle events, add custom tools the AI can call, intercept tool execution, and modify runtime behavior — all with TypeScript.

Whether you want to add a custom linting tool, integrate with your company's internal APIs, enforce coding standards automatically, or build a completely custom AI workflow, the plugin system gives you full control.

This guide covers the plugin API, custom tool creation, event hooks, npm distribution, and real-world plugin examples you can adapt for your own projects.

1Plugin System Overview

OpenCode plugins are TypeScript or JavaScript modules that export a function receiving a context object and returning hooks. There are two ways to load plugins:

• Local files: Place .ts or .js files in .opencode/plugins/(project-level) or ~/.config/opencode/plugins/(global). Loaded automatically at startup.
• npm packages: Add package names to the plugin array in opencode.json. Installed automatically via Bun at startup.

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session",
    "opencode-wakatime",
    "@my-org/custom-plugin"
  ]
}

2Creating Your First Plugin

A minimal plugin that logs every message:

// .opencode/plugins/logger.ts
import type { PluginInput } from "@opencode-ai/plugin";

export default async function(input: PluginInput) {
  return {
    hooks: {
      "message.created": async (message) => {
        console.log(`[LOG] ${message.role}: ${message.content}`);
      },
    },
  };
}

Save this file and restart OpenCode. The plugin loads automatically and logs every message to the console. The PluginInput type provides access to the project context, client, shell, and working directory.

3Custom Tools with tool()

Custom tools are the simplest way to extend OpenCode. Place a file in .opencode/tool/ and the filename becomes the tool name:

// .opencode/tool/deploy_status.ts
import { tool } from "@opencode-ai/plugin";

export default tool({
  description: "Check deployment status for an environment",
  args: {
    environment: tool.schema
      .string()
      .describe("Target environment: staging or production"),
  },
  async execute(args, context) {
    const res = await fetch(
      `https://api.yourcompany.com/deploy/${args.environment}`
    );
    const data = await res.json();
    return `${args.environment}: ${data.status} (v${data.version})`;
  },
});

Now the AI can call deploy_status when you ask "what's the status of staging?" You can also export multiple tools from one file — named exports become filename_exportname.

4Event Hooks & Lifecycle

OpenCode exposes 25+ lifecycle events that plugins can hook into. Key events include:

Hooks can be synchronous or asynchronous. They receive the event data and can modify it, log it, or trigger side effects.

5Plugin Context & SDK

The PluginInput object provides rich context:

• input.project — Project metadata (name, path, configuration)
• input.client — Internal SDK client for programmatic access
• input.$ — BunShell instance for running commands
• input.directory — Project root directory path
• input.worktree — Git worktree path (if applicable)

6Intercepting Tool Execution

One of the most powerful plugin capabilities is intercepting tool calls before they execute. This enables access control, logging, and custom validation:

// .opencode/plugins/safety-guard.ts
export default async function(input) {
  return {
    hooks: {
      "tool.call": async (toolCall) => {
        // Block destructive commands
        if (toolCall.name === "bash" &&
            toolCall.args.command.includes("rm -rf")) {
          return {
            ...toolCall,
            blocked: true,
            reason: "Destructive command blocked by safety plugin",
          };
        }
        return toolCall;
      },
    },
  };
}

7Publishing Plugins to npm

To share your plugin with the community:

1. Create a new npm package with @opencode-ai/plugin as a peer dependency
2. Export your plugin function as the default export
3. Add "opencode-plugin" to your package.json keywords
4. Publish to npm: npm publish
5. Users add your package name to their opencode.json plugin array

// package.json
{
  "name": "opencode-my-plugin",
  "version": "1.0.0",
  "main": "dist/index.js",
  "keywords": ["opencode-plugin"],
  "peerDependencies": {
    "@opencode-ai/plugin": "^1.0.0"
  }
}

8Real-World Plugin Examples

9Plugin Security Considerations

• Plugins run inside the OpenCode process with full access — audit third-party plugins before installing
• Use environment variables for secrets, never hardcode credentials in plugin code
• Scope plugin permissions to the minimum required (e.g., read-only file access)
• Pin npm plugin versions to avoid unexpected updates
• Local plugins in .opencode/plugins/ should be committed to version control for team review

10Lushbinary Plugin Development

Lushbinary builds custom OpenCode plugins for teams that need specialized AI workflows — from internal API integrations to automated code review pipelines and compliance enforcement tools.

❓ Frequently Asked Questions

📚 Sources

• OpenCode Plugin Documentation
• OpenCode GitHub Repository

Content was rephrased for compliance with licensing restrictions. Plugin API details sourced from official OpenCode documentation as of April 2026. APIs may change — always verify on the official site.