opencode-plugin

OpenCode Plugin Development Guide

Complete guide for developing, installing, and troubleshooting plugins for the OpenCode CLI (opencode). Validated against OpenCode v1.14.20 and @opencode-ai/plugin v1.14.19.

Plugin Architecture

OpenCode plugins are ESM JavaScript modules that export an async function. The function receives a PluginInput and returns Promise<Hooks>. Plugins register custom tools, hook into the agent lifecycle, and modify behavior at runtime.

Plugin function called once at load time
  -> returns Hooks object
    -> hooks are called per-event during the session

Plugin File Structure

my-plugin/
├── package.json     # Must have "type": "module", "main": "index.js"
└── index.js         # The plugin code (ESM)

Minimal package.json:

{
  "name": "my-opencode-plugin",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "peerDependencies": {
    "@opencode-ai/plugin": ">=1.14.0"
  }
}

Minimal Plugin

export default async function MyPlugin(input) {
  return {
    // hooks go here
  };
}

This is a valid plugin that does nothing. Every hook is optional.

The Plugin Function

PluginInput

The plugin function receives a single argument with these fields:

export default async function MyPlugin(input) {
  input.client        // OpenCode SDK client (for server API calls)
  input.project       // Project metadata object
  input.directory     // Project root directory (e.g., "~/my-project")
  input.worktree      // Project worktree root
  input.serverUrl     // URL object for the OpenCode server
  input.$             // BunShell instance for running shell commands
  input.experimental_workspace  // Workspace registration API
}

Key fields you'll use most:

• input.directory — the project root. Use this to derive project slugs, locate config files, resolve relative paths.
• input.$ — BunShell for running commands. Usage: await $\git status`.cwd(dir).quiet().text()`
• input.client — OpenCode SDK client for making API calls to the running server.