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".

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 signalsV1 signals
    permissions array, agents, providers, commands, pluginspermission object/string, agent, provider, command, plugin, tools
    mcp.servers, mcp.timeout, server disabledserver names directly under mcp, server enabled
    snapshots, media, update, warming, websearch, worktreesnapshot, attachment, autoupdate, small_model, logLevel, server
    compaction.keep / buffer; model #variant refscompaction.reserved / tail_turns; separate variant field
    ~/.config/opencode/cli.json existstui.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

WhatV2V1
Core settings (system, managed)macOS /Library/Application Support/opencode, Linux /etc/opencode, Windows %ProgramData%\opencode; highest precedence (2.2.5 docs)same directories; see references/config-schema.md (Managed / enterprise)
Core settings (global)~/.config/opencode/opencode.json(c)same
Core settings (project)opencode.json(c) and .opencode/opencode.json(c), searched cwd → filesystem root; .opencode/ files override direct onesopencode.json in cwd or nearest up to the Git root
Terminal client (theme, keybinds)~/.config/opencode/cli.json — global only~/.config/opencode/tui.json + project tui.json
Agents~/.config/opencode/agents/<name>.md, .opencode/agents/<name>.mdsame
Commands~/.config/opencode/commands/<name>.md, .opencode/commands/<name>.mdsame
Skills.opencode/skills/<id>/SKILL.md (+ .claude/skills, .agents/skills)same
Plugins.opencode/plugins/, ~/.config/opencode/plugins/same
Themes~/.config/opencode/themes/*.json, .opencode/themes/*.json (new V2 format)same dirs, V1 format
InstructionsAGENTS.md, then the instructions array (files, globs, HTTP(S) URLs; loaded since 2.0.30); CLAUDE.md is not discoveredAGENTS.md, CLAUDE.md fallback, instructions array
CredentialsSQLite DB (opencode debug paths db) — use /connect / opencode auth~/.local/share/opencode/auth.json — use /connect / opencode auth

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)

TaskV2 (default)V1
Providers, API keys, models, variantsreferences/v2/providers.mdreferences/providers.md
MCP serversreferences/v2/mcp.mdreferences/mcp.md
Agents (built-in and custom)references/v2/agents.mdreferences/agents.md
Permissions, policiesreferences/v2/permissions.mdreferences/permissions.md
Theme, keybinds, terminal UIreferences/v2/cli.mdreferences/tui.md
Plugins (config and API)references/v2/plugins.mdreferences/config-schema.md
Commands, skills, formatters, compaction, misc fieldsreferences/v2/config-schema.mdreferences/config-schema.md
Full schema / unknown fieldreferences/v2/config-schema.mdreferences/config-schema.md
Migrating V1 → V2references/v2/migration.md—

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
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