Claude Code Opus/Sonnet Router

Confirm-first model router for Claude Code.
It automatically runs on UserPromptSubmit and recommends Sonnet 4.6 or Opus based on task complexity.

What This Solves

• Auto-trigger in Claude Code via plugin hook
• Default recommendation: Sonnet 4.6 for daily coding tasks
• Recommend Opus for architecture-scale, cross-module, high-risk tasks
• Require explicit confirmation before applying model switch
• Keep an audit trail in .claude/router-decisions.jsonl

Project Layout

• router/cc-route.py: CLI entrypoint
• router/classifier.py: rule + haiku classifier
• router/policies.py: quality-first routing policy
• router/providers.py: Claude CLI adapter
• router/router_service.py: reusable decision API for CLI and hook
• router/interaction.py: confirm-first interaction messages
• router/hook_bridge.py: UserPromptSubmit hook adapter
• router/config.example.yaml: editable config template
• .claude-plugin/plugin.json: Claude plugin manifest
• hooks/hooks.json: plugin hook registration
• tests/test_classifier.py: classifier tests
• tests/test_policy.py: policy tests
• tests/test_hook_bridge.py: hook bridge tests

Requirements

• Python 3.10+
• Claude Code CLI available as claude in PATH
• Optional: pyyaml if you want YAML config parsing from custom files

Install optional dependency:

python3 -m pip install pyyaml

Usage

Dry-run with explanation (no Claude invocation):

python3 router/cc-route.py \
  --task "Refactor auth architecture and investigate production outage" \
  --mode rule \
  --dry-run \
  --explain

Run through Claude automatically:

python3 router/cc-route.py \
  --task "Add tests for one endpoint and update docs" \
  --mode rule \
  --explain

Use Haiku as pre-classifier:

python3 router/cc-route.py \
  --task "Migrate user schema and update payment pipeline" \
  --mode haiku \
  --explain \
  --dry-run

Routing Rules (v1)

Force opus when task appears to involve:

• security/privacy-sensitive work
• database/schema migration
• production incidents
• architecture-level or multi-file design/refactors
• unknown root cause debugging

Prefer sonnet when task appears to be:

• focused docs/test updates
• small bug fixes with clear scope
• straightforward endpoint or CRUD adjustments

If uncertain and not clearly high-risk, recommend sonnet-4.6 first and let user confirm upgrade.

Planning/design tasks (e.g. architecture design, implementation plan, roadmap/spec) are forced to recommend opus.

Claude Code Hook Mode (Auto-Run)

Install this repo as a local Claude plugin:

claude plugins validate .
claude plugins install .

Restart Claude Code after install.

When enabled, every prompt triggers the router hook:

• it posts a recommendation message
• it does not force a switch automatically
• you confirm with one of:
  • /router use sonnet
  • /router use opus
  • /router keep

After confirmation, apply in-session model switch with:

/model sonnet
# or
/model opus

Additional router controls:

/router status
/router help
/router on
/router off
/router mode rule
/router mode haiku
/router why

Hook State and Logs

• State file: .claude/router-state.json
• Decision log: .claude/router-decisions.jsonl

Config

Default config path: router/config.example.yaml.

Key settings:

• strategy: sonnet-first | balanced | quality-first
• mode: rule | haiku (default: haiku for pre-classification)
• hook.min_prompt_chars: ignore very short prompts
• hook.prefer_sonnet_for_uncertain: keep daily prompts on Sonnet bias
• hook.force_opus_for_planning: force opus recommendation when planning/design intent is detected
• hook.recommend_on_every_prompt: if false, suppress repeats when recommendation == active model
• hook.mode_override: set hook mode without changing global mode

You can override at runtime:

• --mode rule|haiku
• --default-model
• --escalation-model
• --haiku-model
• --binary

Verify

Run tests:

python3 -m unittest discover -s tests -p "test_*.py"

Validate plugin manifest:

claude plugins validate .