Skip to content

CowboyLogic/ai-dev / skills/client-config-opencode

client-config-opencode

Unverified

Manage OpenCode configuration files (V2 native format by default, V1 supported) including MCP servers, providers, models, agents, commands, permissions, policies, skills, plugins, CLI/TUI settings, keybinds, and themes. Use this skill whenever the user wants to view, edit, add, migrate, or understand any opencode setting in opencode.json(c), cli.json, or tui.json. Trigger on: "configure opencode", "add provider", "set model", "add MCP server", "create agent", "configure permissions", "change theme", "add keybind", "show opencode config", "add custom command", "migrate opencode config to V2", or "opencode cli.json".

FileKindSize
CHANGELOG.mdmarkdown18.6 KB
README.mdmarkdown3.9 KB
SKILL.mdskill md8.8 KB
evals/evals.jsonconfig6.7 KB
references/agents.mdmarkdown5.4 KB
references/config-schema.mdmarkdown14.1 KB
references/mcp.mdmarkdown5.1 KB
references/permissions.mdmarkdown5.2 KB
references/providers.mdmarkdown10.8 KB
references/tui.mdmarkdown12.7 KB
references/v2/agents.mdmarkdown5.1 KB
references/v2/cli.mdmarkdown11.1 KB
references/v2/config-schema.mdmarkdown31.8 KB
references/v2/mcp.mdmarkdown10.3 KB
references/v2/migration.mdmarkdown8.9 KB
references/v2/permissions.mdmarkdown16.1 KB
references/v2/plugins.mdmarkdown8.6 KB
references/v2/providers.mdmarkdown21.4 KB
scripts/show-config.pyscript14.2 KB
scripts/update-references.pyscript3.9 KB
sources.jsonconfig7.1 KB

references/v2/plugins.md

View on GitHub
# V2 Plugins Reference

Sources: <https://opencode.ai/v2/docs/plugins/>, <https://opencode.ai/v2/docs/build/plugins/>,
<https://opencode.ai/v2/docs/build/plugins/server/>, <https://opencode.ai/v2/docs/build/plugins/gui/>,
<https://opencode.ai/v2/docs/build/plugins/migrate-v1/>, <https://opencode.ai/v2/docs/cli/plugins/>. Verified against 2.3.0;
the build-docs index was split into `server` and `gui` pages in 2.2.x.

> [!WARNING]
> V1 plugin **implementations do not run in V2**. Configuration is normalized automatically, but plugin code must
> be ported to the new API (`@opencode/plugin`, `Plugin.define`). This is one of V2's three intentional breaking
> changes.

## Configure

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "opencode-acme-plugin",
    "opencode-acme-plugin@1.2.0",
    "@acme/opencode-plugin",
    "./plugins/local",
    "/absolute/path/plugin",
    "file:///home/me/plugins/local",
    { "package": "@acme/opencode-plugin", "options": { "agent": "reviewer", "strict": true } },
  ],
}
```

- Key is `plugins` (plural). V1 `["pkg", {opts}]` tuples become `{ "package", "options" }` objects.
- Relative paths resolve from the **config file** that contains the entry. A configured local path must be a
  **directory** (2.2.x docs); a path to a single file is skipped, so a ported local plugin lives at
  `./plugins/local/index.ts` and is configured as `./plugins/local`.
- Arrays from all applicable configs apply from lowest to highest precedence (they do not replace each other).

## Discovery

Direct `.ts`/`.js` files and immediate plugin package directories load automatically from every discovered
`.opencode/plugins/` and from `~/.config/opencode/plugins/`. V2 also reads the V1 `.opencode/plugin/` directory;
use `plugins/` for new files. A `plugins/` directory beside a project-root `opencode.json` is **not** discovered —
list it explicitly or move it under `.opencode/`.

## Enable / disable

Entries apply in order. `-id` disables, `*` matches every plugin, `prefix.*` matches an ID prefix, and a later ID
re-enables:

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

Built-ins `opencode.config.policy` and `opencode.provider.opencode` ignore removals. Local-model discovery can be
turned off with `-opencode.provider.ollama`, `-opencode.provider.lmstudio`, `-opencode.provider.vllm`.

## Manage

```bash
opencode plugin add opencode-acme-plugin@1.2.0     # installs and adds to global config
opencode plugin add github:acme/opencode-plugin
opencode plugin list [--builtin]
opencode plugin check                              # check package plugins for updates
opencode plugin update [name]
opencode plugin remove opencode-acme-plugin@1.2.0
```

Exact npm versions and full Git commit hashes stay pinned. Config-directory changes reload automatically; unwatched
local dependencies may need `opencode service restart`.

CLI-only plugins go in `cli.json` — see [cli.md](cli.md#cli-only-plugins). Since 2.2.3 TUI plugins need
`@opentui/core` and `@opentui/solid` 0.8.0 or later (2.2.0 required 0.7.0). `plugin check` and `plugin update` also
cover GUI-only plugins.

## Desktop (GUI) plugins

Experimental, since 2.2.0. A package that exports `./gui-experimental` adds panels, commands, or settings to OpenCode
Desktop. The app loads plugins from the server it runs, so configure the plugin in the global `opencode.json(c)` to
use it in every window. **Settings > Extensions > Plugins** lists them when the app's own server is selected; a
plugin's switch turns off only its desktop UI, and **Reload** loads it again after a failure. To turn off the whole
plugin, add `-<id>` to `plugins`. To disable the notice that 2.3.0 adds to new forks, add `"-opencode.fork-notice"` to `plugins` (docs). In 2.2.6 GUI plugins can also add color themes, render or add actions to code blocks, and use native settings and menu
components (release notes and the changed `build/plugins/gui` page; not exercised). Build details are on the `build/plugins/gui` page, which this skill does not
reproduce.

## Minimal V2 plugin

```ts
import { Plugin } from "@opencode/plugin"

export default Plugin.define({
  id: "company.guard",
  async setup(ctx) {
    const strict = ctx.options.strict === true

    await ctx.tool.hook("execute.before", (event) => {
      const input = event.input as { filePath?: string }
      if (strict && event.tool === "read" && input.filePath?.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    })

    await ctx.shell.hook("create.before", (event) => {
      event.env.COMPANY_ENV = "development"
    })

    return () => console.log("unloaded")
  },
})
```

- Every plugin needs a stable `id` (storage is scoped by it).
- `setup(ctx)` may return a cleanup function.
- `ctx.options` holds config options; `ctx.location` gives `directory`, optional `workspaceID`, and `project`.
- The API reference documents context domains for agents, providers, models, commands, integrations, MCP,
  plugins, references, generate, permissions, sessions, skills, storage, tools, VCS, worktrees, web search, and
  events, plus hooks on sessions, permissions, shell, and tools. See the build docs for exact method names.
- Added after 2.0.29 (release notes): `ctx.session.list(...)` (paginated, Effect and Promise APIs; 2.1.0),
  `ctx.session.instructions.entry.put/list/remove` for keyed session instructions that add small updates instead of
  editing the system prompt and survive compaction and reverts (2.2.0), an `experimental.idle` session hook that lets a
  plugin continue work before a session goes idle (2.2.1), and `ctx.experimental.artifact.transform(...)` for artifact
  providers (2.2.4). 2.1.0 renamed provider replay data to `native` on the public SDK, event, and plugin surfaces
  (for example `SessionCompactionResult.providerState` is now `.native`); check any plugin that read the old names.
- `ctx.credential.activate({ credentialID })` makes a saved credential the active one for its integration (in the
  2.0.29 build docs; `credential.activate` reached Effect and Promise server plugins in 2.0.28).
- `ctx.permission.assert` (2.0.29 release notes; not in the build docs) lets an Effect or Promise plugin check the
  configured permission rules and use the native approval prompt. A block or a correction fails the tool call with an
  error carrying the rule's message or the user's feedback.

## V1 hook → V2 API

| V1 | V2 |
|----|----|
| `event` | `ctx.event.subscribe()` |
| `dispose` | Cleanup function returned by `setup` |
| `config` | `transform(...)` on the affected domain |
| `tool` map | `ctx.tool.transform(...)` |
| `auth` | `ctx.integration.transform(...)` |
| `provider` | `ctx.provider.transform(...)` / `ctx.model.transform(...)` |
| `chat.message` | `ctx.session.hook("prompt", ...)` |
| `chat.params` | `ctx.session.hook("context", ...)` (edit `event.options`) |
| `chat.headers` | `ctx.session.hook("model.request", ...)` or `"http.request"` |
| `permission.ask` | `ctx.permission.hook("evaluate", ...)` |
| `tool.execute.before` / `.after` | `ctx.tool.hook("execute.before" \| "execute.after", ...)` |
| `shell.env` | `ctx.shell.hook("create.before", ...)` |
| `tool.definition` | `ctx.tool.transform(...)` |
| `experimental.chat.system.transform` | `ctx.session.hook("context", ...)`, edit `event.system` |
| `experimental.chat.messages.transform` | `ctx.session.hook("context", ...)`, edit `event.messages` |
| `experimental.session.compacting` | `ctx.session.hook("compaction", ...)` |
| `command.execute.before` | Command transform or the prompt hook (no 1:1 global hook) |

These are migration destinations, not exact renames. The V1 context maps as: `directory` → `ctx.location.directory`,
`project` → `ctx.location.project`, `client` → domain methods on `ctx`, the `$` Bun shell → your own process API.

## Supporting V1 and V2 from one package

Default-export an object that spreads `Plugin.define({...})` (V2 reads `id` + `setup`) and adds a V1 `server()`
function (V1 calls it and uses the returned hooks). The migration guide says V1 object entrypoints are supported in
OpenCode `1.18.29` and newer; for older V1 releases use separate function exports.

## Publishing

`package.json` with `"type": "module"`, an `exports["."]` entrypoint, and a dependency on a compatible
`@opencode/plugin` version. An optional `./rpc` export publishes a shared RPC contract.

An Effect plugin declares `effect` as a `peerDependency`: the 2.0.29 docs use `"effect": "^4.0.0"` (the 2.0.26 docs
had `">=4.0.0-rc.112"`), and OpenCode redirects `effect` imports to the host's copy. Effect 4 import paths moved from
`effect/unstable/http` to `effect/http` in the 2.0.29 docs examples.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall