CowboyLogic/ai-dev / skills/client-config-opencode
client-config-opencode
VerifiedManage 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".
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 18.6 KB |
| README.md | markdown | 3.9 KB |
| SKILL.md | skill md | 8.8 KB |
| evals/evals.json | config | 6.7 KB |
| references/agents.md | markdown | 5.4 KB |
| references/config-schema.md | markdown | 14.1 KB |
| references/mcp.md | markdown | 5.1 KB |
| references/permissions.md | markdown | 5.2 KB |
| references/providers.md | markdown | 10.8 KB |
| references/tui.md | markdown | 12.7 KB |
| references/v2/agents.md | markdown | 5.1 KB |
| references/v2/cli.md | markdown | 11.1 KB |
| references/v2/config-schema.md | markdown | 31.8 KB |
| references/v2/mcp.md | markdown | 10.3 KB |
| references/v2/migration.md | markdown | 8.9 KB |
| references/v2/permissions.md | markdown | 16.1 KB |
| references/v2/plugins.md | markdown | 8.6 KB |
| references/v2/providers.md | markdown | 21.4 KB |
| scripts/show-config.py | script | 14.2 KB |
| scripts/update-references.py | script | 3.9 KB |
| sources.json | config | 7.1 KB |
references/v2/migration.md
View on GitHub# V1 → V2 Migration Reference
Source: <https://opencode.ai/v2/docs/migrate-v1/>.
## What actually breaks
V2 has three intentional breaking changes:
1. Plugins use a new API — V1 plugin code does not run (see [plugins.md](plugins.md)).
2. The server API and clients have new contracts (`@opencode/client`).
3. Terminal client config moves from layered `tui.json(c)` files to one global `cli.json` (auto-migrated once;
see [cli.md](cli.md)).
Everything else is meant to stay compatible. V2 reads the same config locations and **normalizes supported V1
fields in memory without rewriting the file**. Converting to native V2 is optional.
> [!CAUTION]
> V1 and V2 share config locations and both use the `opencode` command. Do not point V1 at a file you have
> converted to native V2-only shapes. Keep a copy of the V1 setup until V2 is verified.
>
> The V1 1.19.0 CLI docs list `opencode upgrade --major`, described as "Upgrade to OpenCode 2 and remove
> OpenCode 1". That flag is not in the V1 1.18.29 docs or in the 2.0.27 `opencode upgrade --help`, and the V2 CLI
> command source at 2.0.29 defines no `major` option. Back up the V1 config and any V1 plugins before running it.
## Mixing rules
- V1 and V2 fields may coexist at the **top level**. When both set the same value, a valid native V2 value wins
regardless of key order.
- Mixed V1/V2 members are recognized inside `mcp`, `compaction`, and `experimental` only.
- Individual **agents, providers, commands, and models are not format-inferred** — keep each nested entry entirely
in one format.
- Malformed values, unsupported legacy fields, and conflicting V1/V2 values produce warnings; unrelated settings
still load.
## Top-level renames
| V1 | V2 |
|----|----|
| `autoshare: true` | `share: "auto"` (accepted, but session sharing was removed in 2.0.30 and the 2.2.5 docs drop this row) |
| `permission` (object) + `tools` (booleans) | `permissions` (ordered array) |
| `agent`, `mode` | `agents` (entries from `mode` become primary agents) |
| `snapshot` | `snapshots` |
| `attachment` | `media` |
| `command` | `commands` |
| `reference` | `references` |
| `provider` | `providers` |
| `plugin` | `plugins` |
| `skills: { paths, urls }` | `skills: [ ...paths, ...urls ]` |
| `autoupdate: false` / `"notify"` / `true` | `update: "disable"` / `"notify"` / `"auto"` |
| `small_model` | `agents.title.model` |
| `enabled_providers` / `disabled_providers` | `policies` with `provider.use` (`experimental.policies` is the pre-2.0.29 location, deprecated, and still merges in) |
| Provider `options.setCacheKey` | Provider `compatibility.supportsPromptCacheKey` |
| `subagent_depth` | `experimental.subagent_depth` |
| `logLevel` | `OPENCODE_LOG_LEVEL` env var |
| `server` | `opencode service set ...` / `serve` flags |
Unchanged: `shell`, `model`, `default_agent`, `watcher`, `formatter`, `instructions`, `enterprise`, `tool_output`.
(`instructions` is loaded in V2 since 2.0.30, after `AGENTS.md` files; before that move content into `AGENTS.md`.) `lsp` is preserved but inert.
> [!NOTE]
> The migration guide maps `autoupdate: true` to `update: "auto"`, which installs updates automatically in V2. V1
> 1.19.0 no longer installs updates automatically for `true` (it only notifies; install with `/update`), so the
> mapped value is more aggressive than the V1 behavior it replaces. Use `"notify"` to keep the 1.19.0 behavior.
## Permissions
> [!WARNING]
> V1 asks before accessing paths outside the project. V2 does not: `external_directory` is allowed by default (2.2.x
> docs). To keep the V1 behavior add `{ "action": "external_directory", "resource": "*", "effect": "ask" }` to
> `permissions`. Todos are also off by default in V2; `experimental.todo: true` turns them on.
```jsonc
// V1
{ "permission": { "bash": { "git push *": "ask" }, "edit": "allow" }, "tools": { "websearch": false } }
// V2
{
"permissions": [
{ "action": "shell", "resource": "git push *", "effect": "ask" },
{ "action": "edit", "resource": "*", "effect": "allow" },
{ "action": "websearch", "resource": "*", "effect": "deny" }
]
}
```
Action renames: `bash` → `shell`, `task` → `subagent`, `write`/`patch` → `edit`. A V1 string value such as
`"edit": "allow"` becomes one rule with `resource: "*"`. A V1 pattern object becomes one rule per key, kept in the same
order (inferred from the docs' example; both formats are last-match-wins). A V1 `tools: { "x": false }` becomes `{ action: "x", resource: "*",
effect: "deny" }`.
## Agents
| V1 agent field | V2 |
|----------------|----|
| `prompt` | `system` (Markdown files keep the body) |
| `disable` | `disabled` |
| `permission` | `permissions` |
| `model` + `variant` | `model: "provider/model#variant"` |
| `temperature`, `top_p`, `options` | No agent equivalent that takes effect: agent `request.body` is kept but **not sent** to the model (2.2.x docs). Set them on a model variant (`body` for provider JSON fields, `settings` for provider package options) and reference it as `provider/model#variant` |
| `maxSteps` | `steps` |
| `tools` | `permissions` rules |
| `name` (JSON) | ignored — use the map key |
> [!IMPORTANT]
> A new custom agent without `mode` defaults to `primary` in V2 (V1 defaulted to `all`). Set `mode` explicitly when
> converting. Files moved from `mode/` or `modes/` into `agents/` need `mode: primary`.
## Commands
`command` → `commands`, `subtask` → `subagent` (legacy still accepted), `model` + `variant` →
`model: "provider/model#variant"`. `template`, `description`, `agent` unchanged. Markdown commands move from
`command/` to `commands/` at the same relative path.
## MCP
| V1 | V2 |
|----|----|
| `mcp.<name>` | `mcp.servers.<name>` |
| `enabled: true/false` | `disabled: false/true` |
| `timeout: 30000` | `timeout: { "catalog": 30000, "execution": 30000 }` |
| `experimental.mcp_timeout` | `mcp.timeout.catalog` / `mcp.timeout.execution` |
| `oauth.clientId` / `clientSecret` / `callbackPort` / `redirectUri` | `client_id` / `client_secret` / `callback_port` / `redirect_uri` |
| `tools: { "srv*": false }` | `permissions: [{ action: "srv_*", resource: "*", effect: "deny" }]` |
## Compaction
`preserve_recent_tokens` → `keep.tokens`; `reserved` → `buffer`; `auto` unchanged; `tail_turns` and `prune` are
ignored with a warning.
V2 `buffer` defaults to `"15%"` with a 16k floor in the 2.2.5 docs (10% in the 2.0.29 docs) and also accepts percentages (see [config-schema.md](config-schema.md#compaction)), so a V1
`reserved` value is only carried over when it was set explicitly.
## Providers and models
| V1 | V2 |
|----|----|
| `provider` | `providers` |
| `npm: "@ai-sdk/openai-compatible"` | `package: "aisdk:@ai-sdk/openai-compatible"` |
| `api` | `settings.baseURL` |
| `options` | split into `settings`, `headers`, `body` by request role |
| model `id` | `modelID` |
| model `tool_call`, `modalities` | `capabilities.tools`, `capabilities.input`, `capabilities.output` |
| model `status: "deprecated"` | `disabled: true` |
| model `cost.cache_read` / `cache_write` | `cost.cache.read` / `cost.cache.write` |
| model `options` | `settings` |
| model `variants: { "high": {...} }` | `variants: [{ "id": "high", "settings": {...} }]` |
| `whitelist`, `blacklist`, provider `id` | ignored |
Provider ID consolidation: `azure-cognitive-services` → `azure`; `google-vertex-anthropic` → `google-vertex`.
Migration rewrites these IDs in provider/agent/command/filter fields, but **not** in top-level `model` — update it by
hand.
## Files under `.opencode/`
| Kind | V1 dirs still discovered | Preferred V2 dir |
|------|--------------------------|------------------|
| Agents | `agent/`, `agents/`, `mode/`, `modes/` | `agents/<name>.md` |
| Commands | `command/`, `commands/` | `commands/<name>.md` |
| Skills | `skill/`, `skills/` | `skills/<id>/SKILL.md` (move the whole directory) |
| Plugins | `plugin/`, `plugins/` | `plugins/` |
`CLAUDE.md` is not discovered in V2 — move that guidance into `AGENTS.md`.
## Credentials
V2 imports supported credentials from the legacy `auth.json` into its SQLite database during migration; new
credentials are not written back to `auth.json`.
## Server authentication
V2 servers still use HTTP Basic auth, with these changes (2.2.x docs): `OPENCODE_PASSWORD` sets the password and
`OPENCODE_SERVER_PASSWORD` still works; `OPENCODE_SERVER_USERNAME` is no longer supported, and the username is always
`opencode`.
## Suggested procedure
1. Keep existing config; start V2; verify models, credentials, agents, permissions, MCP servers.
2. Port plugins (mandatory) and server-API integrations.
3. Optionally convert to native V2, one top-level area at a time, keeping each nested entry single-format.
4. Verify with `opencode debug config` and `opencode debug agents`.
The docs' recommended prompt for letting OpenCode convert its own config:
```text
Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format.
Preserve its behavior and all unrelated settings.
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 468k | Updated | Claude CodeCodex | Verified | Install |
| 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: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |