OpenCode Config Kit: V2 Templates, Agents, Commands + V1 Migrator

Set up OpenCode V2 properly in ten minutes: 7 ready opencode.jsonc templates, 10 Markdown agents, 8 slash commands, a V1-to-V2 migrator for your existing config and agent/command files, and a checker that validates everything against OpenCode's published config schema plus the rules the schema can't see (rule order, V1 leftovers, secrets). Python 3.9+, standard library only, works offline.

./tools/demo.sh

It checks examples/broken-v2, migrates a temp copy of examples/v1-project to V2, and re-checks it (0 errors).

python3 tools/install.py /path/to/repo --template safe-default            # all agents + commands + opencode.jsonc
python3 tools/install.py /path/to/repo --agents reviewer,planner --commands review,plan
python3 tools/install.py --global --agents all --commands all              # ~/.config/opencode for every project
python3 tools/install.py /path/to/repo --template ci-headless --dry-run

OpenCode reloads agent and command files automatically. Ask your primary agent "use the reviewer subagent on my changes", or run /review.

python3 tools/opencode_check.py                   # current project: opencode.json(c), .opencode/opencode.json(c), agents, commands
python3 tools/opencode_check.py ~/.config/opencode
python3 tools/opencode_check.py . --json --strict   # CI: exit 1 on warnings too

What it catches (codes in docs/cheatsheet.md):

• Schema errors with did-you-mean hints: unknown keys (permisions), bad enums (effect: maybe), model strings without provider/, MCP entries missing command/url, wrong types.
• Rule order: a rule that never applies because a later rule matches the same calls (the last match wins in V2).
• V1 leftovers: permission, tools, agent, mode, command, provider, plugin, snapshot, autoupdate, small_model, flat mcp entries, skills {paths, urls}, old compaction keys, logLevel/server (ignored by V2), V1 action names in V2 rules (bash, task, write, patch never match), agent files mixing V1 and V2 fields (V1 fields are then ignored), template/subtask/variant in command frontmatter, CLAUDE.md without AGENTS.md.
• Hygiene: literal API keys and tokens (never echoed), $VAR in MCP env/headers (not expanded; use {env:NAME}), plain-http remote MCP, shell allowed for everything with no exceptions, no external_directory rule (V2 allows outside paths by default), subagents without a description, a default_agent that can't be primary, arguments inside !shell blocks.

python3 tools/migrate_v1.py /path/to/repo                    # dry run: unified diff + report
python3 tools/migrate_v1.py /path/to/repo --write            # apply; every changed file gets a .v1.bak copy
python3 tools/migrate_v1.py ~/.config/opencode --write

It follows OpenCode's "Migrate from V1" guide: grouped permission + tools become one ordered permissions array (the V1 * fallback goes first, exceptions after it; bash -> shell, task -> subagent, write/patch -> edit), agent/mode -> agents (prompt -> system, variant joined as model#variant, maxSteps -> steps), command -> commands (subtask -> subagent), MCP servers move under mcp.servers (enabled -> disabled, one timeout -> catalog + execution, OAuth keys to snake_case), providers (npm -> package with aisdk:, api -> settings.baseURL, models and variants), compaction, skills, snapshot, attachment, reference, plugin, autoupdate, small_model. Agent and command files move from agent/, mode/, command/ to agents/ and commands/ with V2 frontmatter (old files become *.md.v1.bak, which OpenCode does not load). Because V1 asked before touching paths outside the project and V2 does not, it adds external_directory: ask unless you pass --no-external-ask. Anything it can't carry over (agent temperature, V1 plugin code) is listed in the report with what to do.

V2 still reads V1 config, so migrating is optional. Do it when you're ready, and don't point a V1 install at converted files.

./run_tests.sh runs 16 tests: every template validated against the bundled published schema; all templates, agents and commands pass the checker with no warnings; the broken example triggers each documented error; the V1 example is schema-valid but flagged; the migrated V1 project validates against the schema with 0 errors and no V1 warnings; a second migration run changes nothing; V1 action names, provider/model conversion and installer no-overwrite behavior. Tested on Python 3.13 and 3.10. During the build, templates and migrated output were also cross-checked with the jsonschema library (Draft 2020-12); the kit itself needs no packages.

• Built from OpenCode's V2 docs and schema as of November 14, 2026. OpenCode moves fast: run the checker with --schema pointing at a fresh copy of https://opencode.ai/config.json when it changes.
• The schema validator covers the JSON Schema features this schema uses, not all of JSON Schema. The YAML reader for frontmatter handles the subset OpenCode files use (maps, lists, scalars, block text), not anchors or tags.
• The migrator drops JSONC comments from rewritten config (the .v1.bak copy keeps them). It does not port V1 plugin code or server API clients; those need the plugin and API migration guides.
• Rule-order checks are conservative: they flag a rule only when a later rule clearly matches everything it matches.
• Permissions are a guardrail, not a sandbox: shell commands run with your user's rights, and the shell scanner is best effort. Model names in templates are examples.
• Not affiliated with or endorsed by OpenCode or its maintainers.