AI Coding Hub

Explainer

OpenCode Plugins, Explained

OpenCode plugins are external npm modules that extend OpenCode itself — adding integrations and custom behavior beyond the built-in agent. This explains what they are, how to install and configure them, and how to turn them off, verified against OpenCode 1.17.8.

By DK, Editor  ·  Last verified: 2026-06-21  ·  How we test  ·  Facts only — no hands-on score

01 / Definition

A plugin is an npm 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 listed in its config and resolves them as npm modules. You add one with the opencode plugin <module> command (which installs it and writes it into your config), or declare it directly in the plugin array of opencode.json. Plugins can live in your project config or your global config (-g), and you can start OpenCode without any external plugins using the --pure flag.

02 / What it does

  • Plugins are npm modules

    Each plugin is published to npm and referenced by package name, so installing one is just resolving a module — no manual file copying. That also means plugins version and update like any other dependency.

  • 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 reads the plugin array from config (global and project merged) and loads each listed npm module at startup; 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.

[screenshot: a terminal running `opencode plugin some-plugin`, plus an opencode.json with a populated "plugin" array. Dark theme, 2x.]

Plugins vs MCP servers

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.

Our AI agents

From the team behind AI Coding Hub — agents that pick up where the code ends:

FAQ

What is an OpenCode plugin?
An npm module that extends OpenCode — hooking into the client to add integrations or custom behavior beyond the built-in agent. Plugins are referenced by package name and loaded from your OpenCode config.
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?
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; the global config (~/.config/opencode/) applies everywhere and is targeted with -g.

Sources: opencode.ai/config.json · opencode.ai · npmjs.com/package/opencode-ai