Explainer
OpenCode Plugins, Explained
OpenCode plugins extend OpenCode itself — adding integrations and custom behavior beyond the built-in agent. They come as npm packages or as local JavaScript/TypeScript files. This explains what they are, how to install and configure them, and how to turn them off; the CLI flags were re-checked on OpenCode 1.18.27 and the loading rules against OpenCode's plugin docs on 2026-10-01.
01 / Definition
A plugin is a module that hooks into OpenCode to change or extend how it behaves — for example adding an integration, a custom workflow, or behavior around the agent loop. Because OpenCode is open source and model-agnostic, plugins let you customize the client without forking it, and share that customization with your team through config.
OpenCode loads plugins from two places (per its plugin docs, checked 2026-10-01): npm packages listed in the plugin array of opencode.json, which it installs automatically with Bun at startup and caches in ~/.cache/opencode/node_modules/, and local JavaScript or TypeScript files in .opencode/plugins/ (project) or ~/.config/opencode/plugins/ (global). The opencode plugin <module> command installs an npm plugin and writes it into your config (-g for the global config), and the --pure flag starts OpenCode without external plugins.
02 / What it does
-
npm packages or local files
A shared plugin is usually an npm package referenced by name, so it versions and updates like any other dependency; OpenCode installs npm plugins with Bun at startup. For your own tweaks you can skip npm entirely and drop a .js or .ts file into .opencode/plugins/ (project) or ~/.config/opencode/plugins/ (global).
-
Two ways to add a plugin
Run opencode plugin <module> to install and register it automatically, or edit opencode.json directly: the "plugin" field is an array whose entries are either a module name (string) or a [name, options] pair when the plugin takes configuration.
-
Global or per-project scope
By default a plugin is added to the project config (./opencode.json), so it travels with the repo and your team. Add -g (--global) to install it into your global config (~/.config/opencode/) so it applies everywhere you run OpenCode.
-
Disable plugins when you need to
Run OpenCode with --pure to start it without loading any external plugins. That is useful for debugging whether a plugin is causing an issue, or for a clean, reproducible run in CI.
03 / How it works
OpenCode loads plugins in this order, per its docs: global config (~/.config/opencode/opencode.json), project config (opencode.json), then the global and project plugin directories. Config entries are either a string module name or a [name, options] tuple for plugins that accept settings. The opencode plugin <module> command resolves the module and writes the entry into config for you (-g targets the global config, -f replaces an existing version), while --pure skips plugin loading entirely. The specific hooks a plugin can implement — what points of the agent it can extend — are defined by OpenCode's plugin API; check the official docs for the current hook surface before writing your own.
MCP servers add external tools the agent can call (GitHub, a database, your vault). Plugins extend OpenCode itself — its behavior and hooks. Use MCP to give the agent tools; use plugins to customize the client.
04 / Who it's for
- Developers who want to customize OpenCode's behavior or add an integration without forking it.
- Teams who want a shared, version-controlled setup — commit the plugin array in the project opencode.json.
- Anyone debugging OpenCode who needs a clean run — start with --pure to rule plugins out.
- Not needed for basic use: OpenCode's built-in agent works fully without any plugins.
05 / Getting started
Install a plugin with opencode plugin <module> (add -g for global), or add its package name to the plugin array in opencode.json. To extend the agent with external tools instead, see the OpenCode MCP guide; for the basics, start with what is OpenCode.
FAQ
- What is an OpenCode plugin?
- A module that extends OpenCode — hooking into the client to add integrations or custom behavior beyond the built-in agent. It is either an npm package listed in your OpenCode config or a local JavaScript/TypeScript file in a plugins directory.
- How do I install an OpenCode plugin?
- Run opencode plugin <module> — it installs the npm module and registers it in your config. Add -g (--global) to install it globally, or -f to replace an existing version. You can also add the module name directly to the "plugin" array in opencode.json.
- How do I disable OpenCode plugins?
- Start OpenCode with the --pure flag to run without loading any external plugins. This is handy for debugging whether a plugin is the cause of a problem, or for a clean run in CI.
- How are OpenCode plugins different from MCP servers?
- MCP servers add external tools the agent calls (e.g. GitHub, a database). Plugins extend OpenCode itself — its behavior and hooks. They are configured separately: MCP servers via opencode mcp / the mcp config block, plugins via opencode plugin / the plugin config array.
- Where are OpenCode plugins configured?
- npm plugins go in opencode.json under the "plugin" array — entries are a module name or a [name, options] pair; project config (./opencode.json) is the default scope and the global config (~/.config/opencode/) is targeted with -g. Local plugin files go in .opencode/plugins/ or ~/.config/opencode/plugins/.