OpenCode Plugins Reference

Updated September 30, 2026 by Alex Sorokoletov

Independent reference, not affiliated with Anomaly. Tables are generated from the OpenCode source at v1.18.33 (v1.18.33). Official documentation: opencode.ai.

An OpenCode plugin is a JavaScript or TypeScript function that receives a context object and returns an object of hooks. OpenCode 1.x defines 21 hooks, including tool.execute.before, tool.execute.after, chat.params and an event hook that sees every bus event. Plugins load from the plugin array in opencode.json and from plugin/ or plugins/ folders.

Does OpenCode have hooks?#

Yes, as plugin functions rather than shell commands. Every hook below runs in the OpenCode process. The trigger-style hooks take (input, output): input describes the call, output is a mutable object, and changes made to output are what OpenCode uses. Plugins run one after another in load order on the same output object, so a later plugin sees earlier plugins' changes. "Called from" lists the OpenCode source files that invoke the hook in this release.

permission.ask is declared in the plugin types but nothing in 1.18.33 invokes it, so a plugin cannot answer permission prompts through it. The event hook is called without being awaited, which makes it observe-only: use it for notifications and logging, and use the trigger hooks for anything that must change behaviour.

What does a plugin function receive?#

client is an SDK client already pointed at the running server, $ is Bun's shell (undefined when OpenCode runs outside Bun), and directory and worktree are the working directory and the project root. The second argument, options, is the object from a ["name", { ... }] entry in the config plugin array.

import type { Plugin } from "@opencode-ai/plugin"

export const EnvGuard: Plugin = async ({ directory }) => ({
  "tool.execute.before": async (input, output) => {
    if (input.tool === "read" && String(output.args.filePath).endsWith(".env")) {
      throw new Error("Reading .env files is blocked")
    }
  },
})

A module can export plugin functions as named exports, or default-export { id, server } where server is the plugin function.

Where do OpenCode plugins go?#

Config directories are ~/.config/opencode, each .opencode/ folder from the working directory up to the git worktree root, ~/.opencode, and $OPENCODE_CONFIG_DIR. Only .ts and .js files directly inside plugin/ or plugins/ load; .mjs files and subfolders are skipped. npm entries without a version install as @latest. OpenCode also runs a background install in each config directory that adds @opencode-ai/plugin, and writes a .gitignore covering node_modules, package.json and lock files where none exists.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-wakatime", ["./tools/my-plugin.ts", { "verbose": true }]]
}

Why is my OpenCode plugin not loading?#

Install, compatibility and load failures surface as a session error naming the plugin. A plugin that throws during setup is logged as "failed to load plugin" and skipped without a visible error, so check the log when a local plugin silently does nothing. Unknown config keys never raise an error in this release: they are dropped when the file is parsed, which is why a misspelled plugins key looks like a plugin that never loaded.

How do OpenCode plugins compare to Claude Code hooks?#

Claude Code hooks are shell commands declared in settings.json that read JSON on stdin and block with exit code 2. OpenCode plugins are in-process functions with no matcher: filter on input.tool inside the hook. The closest equivalents:

• PreToolUse: tool.execute.before. Throw to stop the call (the tool does not run), or change fields of output.args to rewrite its arguments (the tool runs with that same object, so assigning a new object to output.args has no effect). MCP tools pass through the same hook with their <server>_<tool> name.
• PostToolUse: tool.execute.after, with output.title, output.output and output.metadata writable before the result reaches the model.
• UserPromptSubmit: chat.message, which can modify the output.parts array of the incoming message in place.
• PreCompact: experimental.session.compacting, which appends context strings or replaces the compaction prompt.
• SessionStart, Stop, Notification: the event hook with session.created, session.idle or permission.asked, observe-only.
• PermissionRequest: no working equivalent; permission.ask is never called.

Which events can the event hook receive?#

The event hook receives { event } with type and properties for every event on the bus for the plugin's directory. These are the event types in the server's event union:

Frequently asked questions#

Does OpenCode have hooks like Claude Code?#

Yes, through plugins. tool.execute.before and tool.execute.after cover PreToolUse and PostToolUse, chat.message covers UserPromptSubmit, and experimental.session.compacting covers PreCompact. They are TypeScript or JavaScript functions running inside OpenCode, not shell commands, so there is no exit code 2: a tool.execute.before hook blocks a call by throwing an error.

Where do OpenCode plugins go?#

Put a .ts or .js file in .opencode/plugin/ or .opencode/plugins/ for one project, or in ~/.config/opencode/plugin/ or ~/.config/opencode/plugins/ for every project. Files must sit directly in that folder. npm packages and file paths go in the plugin array of opencode.json, where relative paths resolve against the config file that lists them.

Why are my OpenCode plugins not loading?#

Check the key name first: 1.x reads plugin, and a plugins key is ignored with only a log warning. Other causes are a file in a subfolder, a .mjs extension, a module that also exports a non-function value, an npm package whose engines.opencode range excludes your version, or OPENCODE_PURE being set.

What does "unrecognized key plugins" mean in OpenCode?#

The config used the plural plugins key. OpenCode 1.x expects the singular plugin; plugins is the OpenCode 2 name. In 1.18.33 the plural key no longer fails validation: it is dropped with a compatibility warning in the log, and the plugins it lists never load. Rename it to plugin and keep the same array.

Can an OpenCode plugin block a tool call?#

Yes. Throw an error from tool.execute.before and the tool does not run. The hook receives the tool name in input.tool and the arguments in output.args, so it can also rewrite individual arguments instead of blocking. Blocking from permission.ask does not work in this release because OpenCode never calls that hook.

What is the difference between OpenCode plugins, skills and MCP servers?#

A plugin is code that runs inside OpenCode and can change its behaviour: intercept tool calls, edit prompts, add tools through the tool hook, or register provider auth. A skill is instructions the model loads on demand. An MCP server is a separate process exposing tools over the Model Context Protocol, configured under mcp, with each tool governed by its own permission key.

Release-by-release changes: OpenCode version tracker. All OpenCode pages: OpenCode reference index.