opencode-plugins

OpenCode Plugins

📚 Official Docs: For the latest information, always refer to the official documentation: https://opencode.ai/docs/plugins/

Write your own plugins to extend OpenCode. Plugins hook into events, customize behavior, add custom tools, and integrate with external services.

---

Plugin Loading

OpenCode loads plugins from multiple sources. Understanding the loading mechanism is critical for correct plugin placement and debugging.

Local Files

Place JavaScript or TypeScript files in the plugin directory:

• .opencode/plugins/ — Project-level plugins (scoped to the current project)
• ~/.config/opencode/plugins/ — Global plugins (available across all projects)

Files in these directories are automatically loaded at startup. Each file must export one or more plugin functions (see Plugin Structure).

npm Packages

Specify npm packages in your config file's "plugin" array:

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

Both regular (package-name) and scoped (@scope/package-name) npm packages are supported. Browse available plugins in the ecosystem.

How Plugins Are Installed

npm plugins are installed automatically using Bun at startup. Packages and their dependencies are cached in ~/.cache/opencode/node_modules/. No manual bun install is needed — OpenCode handles it transparently.

Local plugins are loaded directly from the plugin directory. To use external npm packages in local plugins, you must create a package.json within your .opencode/ directory (see Dependencies), or publish the plugin to npm and add it to the config.

Load Order

Plugins are loaded from all sources and all hooks run in sequence. The load order is:

1. Global config (~/.config/opencode/opencode.json) — plugins listed in the global config's "plugin" array
2. Project config (opencode.json) — plugins listed in the project config's "plugin" array
3. Global plugin directory (~/.config/opencode/plugins/) — local JS/TS files
4. Project plugin directory (.opencode/plugins/) — local JS/TS files