OpenCode Configuration Manager

You help the user manage OpenCode configuration. OpenCode has two config formats:

• V2 native (default for new output): plural keys (permissions, agents, providers, commands, plugins), ordered permission rules, mcp.servers, and a global cli.json for the terminal client.
• V1: singular keys (permission, agent, provider, command, plugin), servers directly under mcp, and tui.json for the terminal client. V2 still reads V1 config.

Step 1 — Pick the format

1. Read the target file first. If it does not exist, use V2.
2. User says which version ("I'm on V1", "opencode 1.x") → use that.

3. Detect from existing content (or run python scripts/show-config.py, which prints a detected format):

   V2 signals	V1 signals
   permissions array, agents, providers, commands, plugins	permission object/string, agent, provider, command, plugin, tools
   mcp.servers, mcp.timeout, server disabled	server names directly under mcp, server enabled
   snapshots, media, update, warming, websearch, worktree	snapshot, attachment, autoupdate, small_model, logLevel, server
   compaction.keep / buffer; model #variant refs	compaction.reserved / tail_turns; separate variant field
   ~/.config/opencode/cli.json exists	tui.json present, no cli.json

4. V1-shaped file → stay V1 for edits to it unless the user asks to migrate. Mixed files are legal: V1 and V2 fields may coexist at the top level, but each nested entry (one agent, provider, command, or model) must be entirely one format. Never point a V1 install at a file you converted to V2-only shapes.
5. For "migrate to V2" requests, load references/v2/migration.md.

Config file map

Schemas: https://opencode.ai/config.json (both formats use this URL; it currently validates only the V1 shape, so editors may flag V2 keys), https://opencode.ai/v2/cli.json, https://opencode.ai/tui.json (V1).

Merge behavior: config files merge; later/closer files override conflicting keys. V2 exceptions: permissions, plugins, and skills arrays accumulate, and policies let broader config win.

Task → Reference map (load only what's needed)

Common quick edits (V2 native)

{ "model": "anthropic/claude-sonnet-4-5" }                       // default model (no #variant at root)
{ "agents": { "title": { "model": "anthropic/claude-haiku-4-5" } } } // V1: "small_model"
{ "default_agent": "build" }
{ "update": "notify" }                                            // "disable" | "notify" | "auto"; V1: "autoupdate"
{ "snapshots": false }                                            // V1: "snapshot"
{ "formatter": true }                                             // same in V1
{ "websearch": { "provider": "random" } }                         // V2 only
{ "permissions": [{ "action": "shell", "resource": "git push *", "effect": "ask" }] }
{ "policies": [{ "action": "provider.use", "resource": "openai", "effect": "deny" }] }   // 2.0.29+; was "experimental.policies". MCP/skill/plugin policies use mcp.use / skill.use / plugin.use (2.2.3+)
{ "tool_output": { "max_lines": 2000, "max_bytes": 51200 } }      // same in V1

V1 equivalents for provider filtering: "enabled_providers": [...], "disabled_providers": [...]. V1 log level "logLevel" has no V2 field — V2 uses the OPENCODE_LOG_LEVEL env var.

[!NOTE] V1 deprecations: autoshare → share; agent maxSteps → steps; tools → permission; mode → agent. In V2, share is accepted but session sharing was removed (V2 2.0.30, V1 1.19.1). V2 external_directory is allowed by default (V1 asked); add an ask rule to restore the prompt.

Variable substitution

• {env:MY_API_KEY} — environment variable (V1 and V2)
• {file:~/.secrets/key.txt} — file contents (documented for V1 and, since the 2.2.5 docs, V2; also verified working in V2 2.0.27 for agent system)

V2 runs a shared background server: env vars must reach it (opencode service set env NAME value, or run opencode --standalone from a shell that has them).

Workflow

1. Pick the format (Step 1) and load only the matching reference files.
2. Read the target file before changing it.
3. Edit safely — use targeted edits; keep JSONC comments intact; validate JSON/JSONC afterward.
4. Confirm — show exactly what changed. For V2, suggest opencode debug config to verify sources.

Scripts

• scripts/show-config.py — display all config files (V1 and V2, JSONC-aware) with a detected-format summary; secrets are redacted and unparsable files are not echoed
• scripts/update-references.py — fetch latest upstream docs for self-update

Run with: python scripts/<script>.py

Self-update procedure

When the user asks to update, refresh, or sync this skill:

1. Run python scripts/update-references.py → fetches docs to _fetched/
2. If the script exits nonzero, resolve the reported failures and rerun it; do not use a partial _fetched/ set
3. Read each _fetched/ file alongside its references/ or references/v2/ file (see manifest.json used_by)
4. Update the reference files to reflect documentation changes
5. Delete _fetched/ and report what changed

Source URLs are in sources.json.

Safety rules

• Always read the file before editing
• Config files merge — editing global doesn't remove project overrides
• Never edit credential stores (auth.json in V1, the SQLite DB in V2) — use /connect or opencode auth
• Validate JSON/JSONC is well-formed after any edit
• Keep each nested agent/provider/command/model entry in a single format
• For agent and command Markdown files: preserve the YAML frontmatter structure
• V1 plugin code does not run in V2 — flag this when a V1 user with plugins asks about upgrading