OpenCode Config Checker (Free): Validate opencode.json, Agents and Commands

Checks your OpenCode setup before OpenCode silently ignores part of it: opencode.json / opencode.jsonc, .opencode/agents/*.md and .opencode/commands/*.md, validated against OpenCode's published V2 config schema (bundled, works offline) plus the rules the schema can't see. Python 3.9+, standard library only.

python3 tools/opencode_check.py                      # the current project
python3 tools/opencode_check.py ~/.config/opencode   # your global config, agents and commands
python3 tools/opencode_check.py . --json --strict     # CI: JSON output, exit 1 on warnings too
./tools/demo.sh                                       # try it on the two examples

Exit code 1 on errors, so it fits a pre-commit hook or CI step.

• Schema errors with did-you-mean hints: unknown keys (permisions), bad values (effect: maybe), model strings without provider/, MCP entries without command/url.
• Rules that never apply: V2 uses the last matching permission rule, so git push * deny followed by * allow never blocks a push.
• V1 names that V2 never matches: bash, task, write, patch in a V2 permissions array.
• V1 leftovers (still read, deprecated): permission, tools, agent, mode, command, provider, plugin, snapshot, autoupdate, small_model, flat mcp entries, skills {paths, urls}, old compaction keys; fields V2 ignores (logLevel, server, compaction.prune...).
• Agent and command files: frontmatter that mixes V1 and V2 fields (OpenCode then ignores the V1 ones), system in frontmatter, subagents without a description, template / subtask / variant in command frontmatter, arguments inside !shell blocks, legacy agent/, mode/, command/, plugin/ folders, CLAUDE.md without AGENTS.md.
• Secrets and safety: literal API keys and tokens (reported without echoing them), $VAR in MCP env/headers (not expanded; use {env:NAME}), plain-http remote MCP servers, shell allowed for everything with no exceptions, no external_directory rule (V2 reads and edits outside the project without asking by default).

• Built from OpenCode's V2 docs and schema as of November 14, 2026 (schema/config.json, from https://opencode.ai/config.json). When OpenCode changes, pass a fresh copy with --schema.
• The validator covers the JSON Schema features this schema uses; the frontmatter reader covers the YAML subset OpenCode files use.
• Rule-order checks are conservative and only flag clear cases. Passing the checker does not make a setup secure: permissions are a guardrail, not a sandbox.
• Not affiliated with or endorsed by OpenCode or its maintainers.

./run_tests.sh runs 5 tests (Python 3.13 and 3.10).