opencode/packages/www/content/docs/build/plugins.mdx

---
title: "Plugins"
---

Plugins extend OpenCode in-process. They can transform agents, models, commands,
integrations, references, skills, and tools; intercept model requests and tool
execution; and call a subset of the V2 client.

<Callout type="warning">
  The V2 plugin API is beta. Entrypoints, hooks, draft shapes, and configuration may change before the stable release.
  Use the `/v2` exports described on this page.
</Callout>

## Load plugins

Plugins can be loaded from npm packages, explicit local paths, or config
directories. Each module must have one default export containing a unique
plugin `id` and a `setup` function.

### Configuration

Add ordered entries to the `plugins` field in `opencode.json(c)`:

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "opencode-acme-plugin@1.2.0",
    "@acme/opencode-plugin",
    "./plugins/local.ts",
    {
      "package": "./plugins/reviewer.ts",
      "options": {
        "agent": "reviewer",
        "strict": true,
      },
    },
  ],
}
```

A string is either a package specifier or a local path. Local paths must start
with `./` or `../` and resolve relative to the configuration file containing
the entry. Absolute paths and `file://` URLs are also supported. Both scoped
packages and versioned package specifiers are supported.

Use the object form to pass JSON configuration to the plugin. OpenCode passes
`options` unchanged as `ctx.options`; omitted options become an empty object.
The plugin owns validation and defaults for its options.

See [Config](/config#locations) for configuration locations and precedence.
Entries from all applicable files are processed from lowest to highest
precedence rather than replacing the entire array.

### Local discovery

OpenCode automatically scans this directory in every discovered OpenCode config
directory:

```text
.opencode/plugins/
```

The equivalent global directory is `~/.config/opencode/plugins/`. Direct `.ts`
and `.js` children are loaded. An immediate child directory is also loaded as a
package when OpenCode can resolve a string `exports`, `module`, or `main`
entrypoint, or an `index.ts` or `index.js` file.

A `plugins/` directory beside a project-root `opencode.json` is not discovered
automatically. Put it under `.opencode/`, or add its file explicitly with a
relative config entry.

### Enable and disable

A string beginning with `-` disables plugins by their exported `id`. `*`
matches every ID, and a suffix of `.*` matches an ID prefix. Directives are
applied in order:

```jsonc title="opencode.jsonc"
{
  "plugins": ["./plugins/reviewer.ts", "-acme.reviewer", "-opencode.provider.*", "opencode.provider.openai"],
}
```

Package specifiers and local paths locate plugin modules; they are not disable
selectors. Use the `id` from the plugin's default export to disable it. A later
ID entry re-enables a loaded or built-in plugin. Explicit config directives run
after local auto-discovery, so they can disable discovered plugins by ID.

User plugins are activated in configured order between OpenCode's internal
plugin phases. Hooks run sequentially in registration order, and later hooks
observe earlier mutations. Do not depend on the internal phase ordering while
the API is beta.

### Installation and dependencies

OpenCode installs bare package entries and their production dependencies into
an isolated cache. Package installation does not run lifecycle scripts.
Published packages should expose their plugin entrypoint and include every
runtime import in `dependencies`.

Local files and local package directories are imported directly. OpenCode does
**not** install their dependencies. Install dependencies in a `package.json`
visible from the plugin file, for example:

```sh
cd .opencode
bun add @opencode-ai/plugin@beta
```

Match the plugin package version to the OpenCode release you target.

Configuration and discovered plugin files under watched config directories are
reloaded when they change. Reloading replaces the active plugin generation and
releases its scoped registrations. Restart OpenCode after changing an npm
package version or a local dependency when no watched file changed.

## Create a plugin

Export the result of `Plugin.define` as the module default:

```ts title=".opencode/plugins/reviewer.ts"
import { Plugin } from "@opencode-ai/plugin"

export default Plugin.define({
  id: "acme.reviewer",
  setup: async (ctx) => {
    const description =
      typeof ctx.options.description === "string" ? ctx.options.description : "Reviews code for regressions"

    await ctx.agent.transform((agents) => {
      agents.update("reviewer", (agent) => {
        agent.description = description
        agent.mode = "subagent"
      })
    })
  },
})
```

`setup` runs each time the plugin is activated. Register long-lived behavior
during setup; do not wait there on an infinite event stream. It may return a
synchronous or asynchronous cleanup function. OpenCode awaits that cleanup
when the plugin is disabled, reloaded, or shut down:

```ts
setup: async (ctx) => {
  const controller = new AbortController()
  const task = synchronize(ctx, controller.signal)

  return async () => {
    controller.abort()
    await task
  }
}
```

Hook registrations are released automatically with the same plugin scope. Use
the returned cleanup for resources the plugin owns, such as timers, watchers,
connections, and background tasks.

### Context

The plugin context is essentially an [OpenCode server client](/build/client).
Its read and action methods use the same inputs and responses as the client. It
adds plugin-only methods for transforms, runtime hooks, reloads, registrations,
and plugin options.

| Capability             | Available operations                                                                         |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `ctx.agent`            | `list`, `get`, `transform`, `reload`                                                         |
| `ctx.catalog.provider` | `list`, `get`                                                                                |
| `ctx.catalog.model`    | `list`, `get`, `default`                                                                     |
| `ctx.catalog`          | `transform`, `reload`                                                                        |
| `ctx.command`          | `list`, `transform`, `reload`                                                                |
| `ctx.integration`      | `list`, `get`, `connect`, `attempt`, `transform`, `reload`, and connection lookup/resolution |
| `ctx.plugin`           | `list` currently active plugin IDs                                                           |
| `ctx.reference`        | `list`, `transform`, `reload`                                                                |
| `ctx.session`          | `create`, `get`, `prompt`, `command`, `rename`, `synthetic`, `interrupt`, `wait`, and `hook` |
| `ctx.skill`            | `list`, `transform`, `reload`                                                                |
| `ctx.tool`             | `transform` and `hook`                                                                       |
| `ctx.aisdk`            | `hook`                                                                                       |
| `ctx.event`            | `subscribe` to the current public server event stream                                        |
| `ctx.options`          | Readonly options from the matching config object                                             |

### Transform hooks

Transform hooks let a plugin modify how OpenCode is configured. Use them to add
or remove definitions, override settings, choose defaults, and provide tools or
other sources.

| Transform               | Draft operations                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| `agent.transform`       | `list`, `get`, `default`, `update`, `remove`                                                            |
| `catalog.transform`     | Provider `list`, `get`, `update`, `remove`; model `get`, `update`, `remove`; default model `get`, `set` |
| `command.transform`     | `list`, `get`, `update`, `remove`                                                                       |
| `integration.transform` | Integration `list`, `get`, `update`, `remove`; method `list`, `update`, `remove`                        |
| `reference.transform`   | `add`, `remove`, `list`                                                                                 |
| `skill.transform`       | `source`, `list`                                                                                        |
| `tool.transform`        | `add`                                                                                                   |

Here's an example that keeps models synced from a remote source:

```js title=".opencode/plugins/remote-models.js"
import { Plugin } from "@opencode-ai/plugin"

export default Plugin.define({
  id: "acme.remote-models",
  setup: async (ctx) => {
    let models = []

    await ctx.catalog.transform((catalog) => {
      for (const model of models) {
        catalog.model.update(model.providerID, model.id, (draft) => Object.assign(draft, model))
      }
    })

    const refresh = async () => {
      const response = await fetch("https://example.com/opencode/models.json", {
        signal: AbortSignal.timeout(10_000),
      })
      if (!response.ok) return
      models = await response.json()
      await ctx.catalog.reload()
    }

    await refresh()
    const timer = setInterval(() => void refresh().catch(console.error), 60_000)
    return () => clearInterval(timer)
  },
})
```

`ctx.catalog.reload()` replays every catalog transform to derive the new
catalog. Each plugin's logic remains composed with the others, so a later
plugin can still modify models added by an earlier one. The catalog updates
without restarting OpenCode.

### Runtime hooks

Runtime hooks intercept live operations:

| Hook                                          | Mutable fields                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `ctx.aisdk.hook("sdk", callback)`             | `sdk`, after inspecting `model`, `package`, and `options`                      |
| `ctx.aisdk.hook("language", callback)`        | `language`, after inspecting `model`, `sdk`, and `options`                     |
| `ctx.session.hook("context", callback)`       | `system`, `messages`, and the `tools` record immediately before model dispatch |
| `ctx.session.hook("http.request", callback)`  | `request`, immediately before provider dispatch                                |
| `ctx.session.hook("http.response", callback)` | `response`, immediately after the provider responds                            |
| `ctx.tool.hook("execute.before", callback)`   | `input`, before the selected tool executes                                     |
| `ctx.tool.hook("execute.after", callback)`    | Terminal `result` on success or `error` on failure                             |

HTTP hooks can modify requests and responses. They apply to native models; AI
SDK models do not currently pass through these hooks. Request and response
bodies are one-shot streams. Use `clone()` when you intentionally need a
separate reader, but be aware that its slower branch may buffer data. To inspect
or modify chunks while preserving streaming, replace the body with one piped
through a `TransformStream`.

```ts
await ctx.session.hook("http.request", (event) => {
  event.request.headers.set("x-session-id", event.sessionID)
})

await ctx.session.hook("http.response", (event) => {
  event.response = new Response(event.response.body, {
    status: event.response.status,
    headers: { ...Object.fromEntries(event.response.headers), "x-plugin": "enabled" },
  })
})
```

For example, remove a tool from selected model requests and normalize another
tool's input:

```ts title=".opencode/plugins/guards.ts"
import { Plugin } from "@opencode-ai/plugin"

export default Plugin.define({
  id: "acme.guards",
  setup: async (ctx) => {
    await ctx.session.hook("context", (event) => {
      delete event.tools.write
    })

    await ctx.tool.hook("execute.before", (event) => {
      if (event.tool !== "lookup" || typeof event.input !== "object" || event.input === null) return
      event.input = { ...event.input, source: "plugin" }
    })
  },
})
```

A hook failure fails the operation it intercepts. Keep runtime hooks fast and
handle expected errors inside the callback.

## Examples

### Add a tool

Register a structural tool definition with a name and registration options.
Define its input with JSON Schema and use an async executor:

```js title=".opencode/plugins/greeting.js"
import { Plugin } from "@opencode-ai/plugin"

export default Plugin.define({
  id: "acme.greeting",
  setup: async (ctx) => {
    await ctx.tool.transform((tools) => {
      tools.add("greeting", {
        description: "Create a greeting",
        input: {
          type: "object",
          properties: {
            name: { type: "string" },
          },
          required: ["name"],
          additionalProperties: false,
        },
        output: {
          type: "object",
          properties: { greeting: { type: "string" } },
          required: ["greeting"],
          additionalProperties: false,
        },
        execute: async ({ name }) => {
          const text = `Hello, ${name}!`
          return {
            output: { greeting: text },
            content: text,
          }
        },
      })
    })
  },
})
```

Unsupported characters in tool names are normalized to underscores. Namespace
segments must begin with a letter, contain at most 64 letters, digits,
underscores, or hyphens, and are joined with dots. Pass the optional third
argument to `tools.add` to configure the registration with
`{ namespace, codemode }`:

- `namespace` prefixes and groups the exposed tool name.
- `codemode` defaults to `true` and makes the tool available through the
  `execute` CodeMode tool. Set `codemode: false` to expose it directly to the
  provider.

The executor receives a second context argument containing `id`, `sessionID`,
`agent`, `messageID`, and `progress`. A tool with `output`
must return `output`; Effect and Standard Schema codecs validate it, while raw
JSON Schema definitions enforce JSON compatibility only. A tool
without `output` returns model-visible `content` instead.

### Add a command

```js title=".opencode/plugins/review-command.js"
import { Plugin } from "@opencode-ai/plugin"

export default Plugin.define({
  id: "acme.review-command",
  setup: async (ctx) => {
    await ctx.command.transform((commands) => {
      commands.update("review", (command) => {
        command.description = "Review the current changes"
        command.template = "Review the current changes for correctness and missing tests."
      })
    })
  },
})
```

### Set the default model

```js title=".opencode/plugins/default-model.js"
import { Plugin } from "@opencode-ai/plugin"

export default Plugin.define({
  id: "acme.default-model",
  setup: async (ctx) => {
    await ctx.catalog.transform((catalog) => {
      catalog.model.default.set("anthropic", "claude-sonnet-4-5")
    })
  },
})
```

## Publish a package

A package plugin uses the same default export as a local plugin. A minimal
manifest is:

```json title="package.json"
{
  "name": "opencode-acme-plugin",
  "version": "1.0.0",
  "type": "module",
  "exports": "./src/index.ts",
  "dependencies": {
    "@opencode-ai/plugin": "beta"
  }
}
```

Use versions compatible with the OpenCode release you target and test the
installed package, not only a workspace-linked copy. Because the plugin API is
beta, publish compatible plugin updates when V2 entrypoints or contracts
change.

## Verify loading

List active plugin IDs through the V2 API:

```sh
opencode2 api get /api/plugin
```

If a plugin is absent, check the server log described in
[Troubleshooting](/troubleshooting#read-logs). Invalid modules and setup failures are
logged; one failing package does not prevent unrelated valid packages from
being resolved.

## Effect

OpenCode provides a first-class Effect API for plugins through the
`@opencode-ai/plugin/effect` entrypoint. Install `effect` alongside the
plugin package and export an `effect` function instead of `setup`:

```sh
bun add @opencode-ai/plugin@beta effect
```

```ts title=".opencode/plugins/reviewer-effect.ts"
import { Plugin } from "@opencode-ai/plugin/effect"
import { Effect } from "effect"

export default Plugin.define({
  id: "acme.reviewer-effect",
  effect: (ctx) =>
    Effect.gen(function* () {
      yield* ctx.agent.transform((agents) => {
        agents.update("reviewer", (agent) => {
          agent.description = "Reviews code for regressions"
          agent.mode = "subagent"
        })
      })
    }),
})
```

Context operations return Effects. The plugin effect is scoped, so finalizers,
fibers, and registrations are released when the plugin reloads or unloads.
OpenCode does not expose its private Core services to the plugin; use the
capabilities on `ctx`.

Typed tools can use `Schema` from `effect`. Effect and Promise plugins use the
same `tools.add(name, tool, options?)` registration shape. Effect executors
return an Effect and may fail with the typed tool failure channel.