OpenCode plugins: install, configure and port to version 2
Plugins in OpenCode 2: the plugins key, the .opencode/plugins folder, opencode plugin add, why version 1 plugins stop working, and what one can reach.
In OpenCode 2, a plugin is a TypeScript or JavaScript package that runs inside OpenCode’s server and adds tools, hooks, integrations, commands or agents. List it under plugins (plural) in opencode.json, drop it in .opencode/plugins/ or ~/.config/opencode/plugins/, or install a package with opencode plugin add <package>. Plugins written for version 1 do not run in version 2: the config key was plugin, the API is new, and the code has to be ported by hand. A plugin is code, not a setting, so add only ones you would run yourself: OpenCode does not sandbox it. This page describes OpenCode 2.3.0, released November 13, 2026.
opencode plugin add <package>@<version> # install a pinned version
opencode plugin list # what is installed
opencode plugin list --builtin # including OpenCode's own
opencode plugin check # look for updates
opencode plugin update # apply them
opencode plugin remove <package>@<version>CopiedWhich version you have
Two versions of OpenCode are live, and the short install line, curl -fsSL https://opencode.ai/install | bash, still installs version 1 (it gave 1.19.5 on November 13, 2026); version 2 comes from https://opencode.ai/v2/install or opencode upgrade --major. opencode --version tells you which you are on. A tutorial written before version 2 describes the old plugins, so check what you read against version 2’s plugin docs. The OpenCode install guide covers the split and the upgrade.
Adding plugins in the config
The plugins page takes npm packages, with or without a version, scoped packages, local directories, file:// URLs, and an object form when the plugin takes options:
{
"$schema": "https://opencode.ai/config.json",
"plugins": [
"<package>",
"<package>@<version>",
"@<scope>/<package>",
"./plugins/local",
{ "package": "<package>", "options": { "agent": "reviewer", "strict": true } }
]
}Copied“Relative paths resolve from the config file containing the entry,” and a local path has to be a directory: a path to a single file is skipped. The global file is ~/.config/opencode/opencode.json; a project’s is opencode.json at its root or inside .opencode/, as the config page lists. When several files carry a plugins list, the lists are merged by precedence rather than the nearest one replacing the rest. OpenCode’s config guide sets out that order and how to see it with opencode debug config.
Two folders are read without any config at all. OpenCode loads every .ts and .js file, and every package directory, it finds in a project’s .opencode/plugins/ and in ~/.config/opencode/plugins/. A plugins/ folder beside a project-root opencode.json is not one of them; it has to be listed, as ./plugins/local is above.
The opencode plugin command
opencode plugin (“Manage plugins” in 2.3.0’s help) handles global package plugins: the commands at the top of this page add, list, check, update and remove them. add accepts what npm accepts for a source, including Git:
opencode plugin add @<scope>/<package>@latest
opencode plugin add github:<owner>/<repo>
opencode plugin add git+ssh://git@github.com/<owner>/<repo>.git#main
opencode plugin add 'github:<owner>/<repo>#main::path:packages/<plugin>'CopiedThe last form installs one package from a subdirectory of a repository. Local paths are not accepted by add (put them in the config), and neither are tarballs or npm aliases.
Updates, pinning, and reloads
At startup OpenCode loads plugins it has cached straight away, “installs missing packages in the background” and “checks unpinned npm and Git plugins for updates without changing the installed package.” An update lands when you run opencode plugin update, for everything outdated or for one package named after it. “Exact npm versions and full Git commit hashes stay pinned,” so a version like @1.2.0 or a full commit hash is the way to keep a plugin exactly where it is.
A change in a watched config directory reloads by itself. A change to a local plugin’s own dependencies outside those directories may not, and the docs’ answer is a restart. In version 2 the plugin runs in OpenCode’s background service, the one process per user account that every terminal and browser window talks to, so the restart is:
opencode service restartCopiedTurning plugins off
Entries are read in order. A leading - disables a plugin ID or a wildcard, * matches every plugin, a trailing .* matches an ID prefix, and a later entry switches a plugin back on. This keeps everything except OpenCode’s provider plugins, then brings OpenAI’s back and drops one more:
{
"plugins": ["*", "-opencode.provider.*", "opencode.provider.openai", "-acme.reviewer"]
}CopiedOpenCode’s own features are partly built-in plugins, which opencode plugin list --builtin shows. Two of them cannot be removed: “Two built-in plugins ignore removals so that a repository cannot switch off” organisation policy, opencode.config.policy and opencode.provider.opencode.
Version 1 plugins in version 2
The migration page is direct: “V1 plugin implementations do not run in V2. Moving a file or renaming its config entry is not enough.” The config side carries over. Version 2 still reads a version 1 opencode.json, normalising it in memory without rewriting the file, but the plugin’s code is what stops working. To move the config by hand, rename plugin to plugins, turn a package-and-options pair into an object, and make a local plugin a directory:
// version 1
"plugin": ["opencode-example-plugin", ["./plugin/local.ts", { "enabled": true }]]
// version 2
"plugins": ["opencode-example-plugin", { "package": "./plugin/local", "options": { "enabled": true } }]CopiedThe ported file goes to ./plugin/local/index.ts, and plugin files OpenCode should find by itself go in .opencode/plugins/.
The API underneath changed shape. A version 1 plugin was a function that received directory, project, client and Bun’s $ shell, and returned one object of tools and hooks keyed by name. A version 2 plugin default-exports Plugin.define with an id and a setup(ctx), and registers each hook on the part of OpenCode that owns it. The plugin migration guide maps the old hooks to their new homes, for example:
tool.execute.beforebecomesctx.tool.hook("execute.before", …)chat.messagebecomesctx.session.hook("prompt", …)permission.askbecomesctx.permission.hook("evaluate", …)shell.envbecomesctx.shell.hook("create.before", …)eventbecomesctx.event.subscribe(), anddisposea cleanup function returned fromsetup
It calls these “migration destinations, not always exact renames.” Hooks receive one mutable event instead of separate input and output objects, options arrive as ctx.options, and there is no single global config object to edit. Some version 1 hooks have no direct equivalent: the experimental ones, command.execute.before, and the $ helper, which a version 2 plugin replaces by importing the process API it needs itself.
What a version 2 plugin looks like
The package to build against is @opencode/plugin, versioned with OpenCode itself (2.3.0 at the 2.3.0 release). The build guide’s smallest server plugin, in .opencode/plugins/example/index.ts:
import { Plugin } from "@opencode/plugin"
export default Plugin.define({
id: "example",
async setup(ctx) {
await ctx.storage.set("loaded", true)
},
})CopiedA plugin package can have up to three parts. The server part “runs in the OpenCode server” and adds “tools, hooks, integrations, commands, and agents.” A terminal part, from @opencode/plugin/tui, runs in the terminal interface, and a desktop part, from @opencode/plugin/gui, adds panels, commands or settings to OpenCode Desktop, configured in the global file and shown under Settings, Extensions, Plugins. A plugin that only changes the terminal goes in a separate cli.json, runs on the machine you type on, and stays active when that terminal is connected to OpenCode on another machine.
What a plugin can reach
The context a version 2 plugin is handed is, in the migration guide’s words, “both an OpenCode client and the plugin API,” with domains that include sessions, permissions, integrations, MCP servers, skills, storage, version control, worktrees and web search. Its hooks sit on the prompt, on every tool call before and after it runs, on the request sent to the model, and on the permission check itself, which is the point of hooks, and also why one written carelessly or with bad intent can do the opposite of what you asked the agent for.
Beyond OpenCode’s own API, a plugin is a module running in the server process, and OpenCode’s security policy says “OpenCode does not sandbox the agent” and that the permission system “is not designed to provide security isolation.” A module in an unsandboxed process runs with your user account’s rights, so a plugin can read your files and keys, run programs and open network connections. The same policy puts config files out of its scope (“Users control their own config”), and a project’s .opencode/plugins/ is loaded automatically, so a repository you clone can bring plugins with it. Read that folder, and the project’s plugins list, before you start OpenCode in a repository you didn’t write, and pin the versions of the packages you keep. If you need a hard boundary, the policy’s own advice is to run OpenCode in a container or a machine of its own.
Much of what people reach for a plugin to do needs less: skills add instructions the agent loads when it needs them, and MCP servers add tools from a separate program or a remote service. Pi’s equivalent of a plugin is an extension, which runs with the same rights; the guide to Pi extensions covers that side, and Pi against OpenCode compares the two agents as a whole.