Auto Model Router
IuriiTurok/auto-model-router
Classifica prompts e roteia entre Haiku/Sonnet/Opus com paralelismo seguro
Ver no GitHubSkill que classifica prompts por complexidade e roteia automaticamente entre Claude Haiku, Sonnet e Opus (com suporte a paralelismo seguro). Reduz custos rodando trabalhos simples em modelos menores enquanto mantém a sessão pai no modelo original, com fallback por decision block JSON.
Instalação
npx convez-ai IuriiTurok/auto-model-router1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Otimizar custo de sessões Claude prolongadas
- Delegar tarefas simples a Haiku enquanto mantém contexto em Opus
- Executar múltiplas subtarefas em paralelo com modelos apropriados
- Plan-mode com decomposição automática e síntese
Veredito

Ferramenta muito prática para reduzir custos em fluxos Claude intensivos, com inteligência real sobre paralelismo seguro e fallbacks. Implementação madura (v0.5) com audit logging e relatórios, mas exige disciplina na instalação e compreensão profunda de decision blocks e plano-mode para máxima eficiência.
README
A tradução para o português deste README ainda está na fila.
auto-model-router
Per-prompt model routing for Claude Code. Classifies every user prompt into a tier (trivial / standard / complex / deep), picks the matching model (haiku / sonnet / opus), and either auto-delegates the work to a worker subagent or asks before doing so.
The point: stop running every session on Opus when most of the work
fits Sonnet or Haiku. The plugin keeps the parent session on whatever
you launched with and dispatches real work to a model-matched worker
subagent. New sessions can be launched on the right model from the
start via the bundled cc-route CLI wrapper.
Parallel by default where it's safe. Multi-part prompts and plan-mode steps follow one spine — decompose → cheapest sufficient model per task → run independent pieces in parallel → synthesize. That's faster (wall-clock), cheaper (many small Haiku/Sonnet contexts beat one giant Opus-rate context), and higher quality (a dedicated synthesis pass). Agents only run concurrently when they can't collide: read-only tasks are always safe, writers run together only when their file sets are disjoint, and overlapping writers are serialized (or isolated in a git worktree). See Plan-mode behaviour.
v0.5 additions: a fourth worker agent router-fable (manual/override-only
via #model=fable — never auto-dispatched) for frontier-stakes synthesis steps;
an optout tier so #noshift/#noroute/disabled-project prompts emit a clean
tier=optout, band=none signal instead of falling through silently; and a
continuity flag in the decision block that tells the parent to prefer staying
inline when the user is mid-iteration.
Install
See INSTALL.md. TL;DR:
/plugin marketplace add <owner>/auto-model-router
/plugin install auto-model-router@auto-model-router-mp
Then optionally run bin/install.sh to add the cc-route CLI to PATH.
How it works
prompt → UserPromptSubmit hook
↓
classify (heuristic → Haiku fallback → default)
↓
decide band (auto / ask / silent)
↓
inject <router-decision> JSON into context
↓
parent session reads block, auto-model-routing skill fires
↓
band=auto + fanout → Branch E: decompose → parallel batch of agents
band=auto → Agent(subagent_type="router-{model}", prompt=…)
band=ask → AskUserQuestion chip, then dispatch (or fan out)
band=none → ignore, do inline
IN PLAN MODE (parent-detected) → plan-with-models runs parallel waves
↓
worker(s) return → parent synthesizes 1-2 sentence summary → audit log
Plan mode is parent-authoritative: the UserPromptSubmit hook can't see
plan state (the payload has no plan flag), so the parent decides from its own
context and the plan_mode field in the decision block is best-effort only.
Goals & reporting
The router serves three north-star goals, defined in GOALS.md:
- Cost efficiency — estimated $ saved by routing work to the cheapest sufficient model (vs an all-Opus counterfactual).
- Quality — user-correction rate, router-delegated vs inline. The router cohort must not be worse.
- Time-to-results — time-to-first-approval + wall-clock saved by parallelism.
/router-report [7d|1d|yesterday] [--llm-judge] scores all three over a
window. It reads the audit log + session transcripts (joined by prompt_sha),
writes a dated report to ~/.claude/cache/router/reports/, appends lessons
learned, and offers concrete, data-derived tweaks (it never applies them
silently). The deterministic core is tools/usage-report.py (run it directly
with --json for machine output); correction detection is heuristic unless
--llm-judge adds a Haiku pass. All figures are estimates and the
router-vs-inline timing comparison is correlation, not causation.
/router-loop is the autonomous closed-loop counterpart to /router-report:
where the report offers tweaks for you to apply by hand, the loop runs a
PROPOSE → COMMIT → EXECUTE → EVALUATE → DECIDE cycle that proposes one
auto_threshold step, gates it offline (fixtures + a projected-band sanity
check), applies it to a loop-private git repo (router-loop/auto, never
pushed), then confirms-or-reverts it against realized KPIs — with quality
(GOALS.md §2) as the hard veto and git revert as the rollback. It is
rung-2, config-only (the global auto_threshold), and self-rolling-back; the
report's "offer, don't apply" contract is untouched. See tools/router_loop.py
and GOALS.md.
Components
auto-model-router/
├── .claude-plugin/
│ ├── marketplace.json # single-plugin marketplace manifest
│ └── plugin.json # plugin metadata
├── GOALS.md # the three north-star KPIs (cost/quality/time)
├── hooks/
│ ├── auto-router.py # UserPromptSubmit hook — the classifier (+ fanout)
│ ├── post-agent-audit.py # PostToolUse — outcome capture (tokens, wall, group)
│ ├── pre-agent-mark.py # PreToolUse — start-time marker for wall-clock
│ ├── waves.py # pure DAG→waves + non-interference batching
│ ├── pricing.py # per-MTok price table for the cost KPI
│ └── hooks.json # hook registration (auto-loaded by Claude Code)
├── skills/
│ ├── auto-model-routing/SKILL.md # parent: read decision → delegate / fan out
│ └── plan-with-models/SKILL.md # plan-mode: tags + parallel wave executor
├── agents/
│ ├── router-haiku.md # worker subagent_type, model=haiku
│ ├── router-sonnet.md # worker subagent_type, model=sonnet
│ ├── router-opus.md # worker subagent_type, model=opus
│ └── router-fable.md # worker subagent_type, model=fable (manual/override-only)
├── commands/
│ ├── route.md # /route <prompt> — force re-classify
│ ├── route-status.md # /route-status — recent decisions + parallelism
│ └── router-report.md # /router-report — KPI report + lessons + offers
├── tools/
│ ├── analyze-audit.py # distribution + parallelism analyzer
│ └── usage-report.py # KPI usage report (cost / quality / time)
├── tests/
│ ├── fixtures.jsonl # golden classifier cases (+ fanout)
│ ├── run.sh # full suite entrypoint (fixtures + both py suites)
│ ├── test_waves.py # wave/non-interference unit tests
│ └── test_usage_report.py # KPI report unit tests
├── bin/
│ ├── cc-route # CLI wrapper for session-launch routing
│ └── install.sh # post-install: symlink cc-route to PATH
├── INSTALL.md
├── LICENSE
└── README.md
When installed via the marketplace flow, Claude Code auto-discovers the
hook, skills, agents, and commands from the standard subdirectories.
No manual settings.json edit needed.
Confidence bands
auto(≥ 0.75): parent auto-dispatches viaAgentand reports the worker's result. No interactive step.ask(0.60–0.75): parent callsAskUserQuestionwith options[Use <model>] [Use Opus] [Stay on current]. Honours your answer.none(< 0.60): silent. Hook emits an audit log entry but injects no context.
Knobs
| Mechanism | Effect |
|---|---|
#noshift in the prompt | Skip routing entirely for this prompt (opt-out, tier=optout). |
#noroute in the prompt | Alias for #noshift. |
#model=opus (or sonnet/haiku/fable) | Force-route to that tier; confidence 1.0, band=auto. |
Env CC_ROUTER_DISABLE=1 | Disable the hook globally for the shell. |
Env CC_ROUTER_AUTO_THRESHOLD=0.9 | Raise/lower the auto-delegate cutoff (default 0.75). |
Env CC_ROUTER_ASK_THRESHOLD=0.6 | Raise/lower the ask cutoff (default 0.60). |
Env ANTHROPIC_API_KEY | Enables the Haiku fallback classifier for ambiguous cases. Without it, low-confidence prompts default to Sonnet/ask. |
Project .claude/router.json | Per-project overrides (see below). Found by walking up from cwd. |
Per-project overrides — .claude/router.json
Drop a .claude/router.json at any project root to pin behaviour for
that tree. Keys (all optional):
{
"disabled": false, // turn off routing for this project entirely
"default_model": "opus", // pin every prompt; confidence 0.95, band=auto
"auto_threshold": 0.85, // override the global auto cutoff
"ask_threshold": 0.6, // override the global ask cutoff
"rules": [
// first match wins, checked before heuristics
{
"match": "design|asset|mascot|logo", // regex (because "regex": true)
"regex": true,
"model": "sonnet",
"reason": "design/asset work — Sonnet is plenty",
},
{
"match": "cad|firmware|geometry",
"regex": true,
"model": "opus",
"reason": "engineering / hard reasoning — keep Opus",
},
],
}
Common patterns to start from:
- Engineering-heavy project (CAD, firmware, complex distributed
systems, hard refactors):
{"default_model": "opus"}plus a haiku rule for trivial lookups. - Design / asset / content project:
{"default_model": "sonnet"}. - SaaS feature work / spec writing:
{"default_model": "sonnet", "rules": [{"match": "refactor.*architecture", "regex": true, "model": "opus"}]}. - Docs-only project:
{"default_model": "sonnet"}or even{"default_model": "haiku"}if the writes are mostly mechanical.
You can also commit .claude/router.json to your team repo — it
applies to anyone running the plugin in that tree.
Cache & audit log
- Classification cache:
~/.claude/cache/router/<sha256>.json, 7-day TTL./routebypasses by deleting the entry. - Audit log:
~/.claude/cache/router/audit.jsonl. One line per decision; includes prompt SHA prefix, decision, outcome (injected/silent)./route-statusreads from this.
Both directories live under ~/.claude/ (per-user), not in the
plugin — they survive plugin upgrades and uninstalls.
Slash commands
/route <prompt>— re-run the classifier on<prompt>, ignoring cache. Useful after editing the heuristic rules. Flags:--show-last,--force-opus|sonnet|haiku./route-status— show the last 20 decisions and a rolling 7-day distribution by model and band.
CLI wrapper — cc-route
For new sessions, cc-route classifies the first prompt before
launching claude, so the session starts on the right model.
cc-route "list all open PRs" # → claude --model haiku "..."
cc-route "design a new payment system" # → claude --model opus "..."
cc-route --dry-run "ambiguous prompt" # classify only, print decision
cc-route --opus "force opus" # bypass classifier
cc-route --show-last # print last audit log entry
cc-route "fix bug" --resume <session-id> # extra flags pass through to claude
Run bin/install.sh once after plugin install to symlink cc-route
into ~/.local/bin/. Use it as a habit when starting a new task that
you suspect doesn't need Opus — much higher-leverage than remembering
to /model sonnet after the session already started on Opus.
Verifying it's working
# Heuristic dry-run on a trivial prompt — should print band=auto, model=haiku.
echo '{"prompt":"list all open PRs"}' | \
python3 <path-to-plugin>/hooks/auto-router.py | \
python3 -c 'import sys,json;d=json.load(sys.stdin);print(d["hookSpecificOutput"]["additionalContext"][:200])'
# Audit log line-count grows.
wc -l ~/.claude/cache/router/audit.jsonl
In a real session, watch the chat for the [auto-router] … header line
— it confirms the hook fired. Use /route-status periodically to see
the distribution. Common targets after a few weeks of use:
- By session count: Opus ~30–40%, Sonnet ~60–70%, Haiku trace.
- By quota burn: Opus still ~85–90% (it's used on the harder/longer sessions), Sonnet ~10–15%. Most savings come from killing long, repetitive low-reasoning sessions that bloat on Opus today.
Plan-mode behaviour
Plan mode is parent-authoritative — the parent recognizes it from its
own context, not the hook (the UserPromptSubmit payload carries no
plan-mode flag, so the decision block's plan_mode is best-effort and is
usually false even mid-plan). When in plan mode, the parent uses the
plan-with-models skill, which:
- requires every step to carry
Model:,Effort:, andFiles:tags; - builds a dependency DAG from
Depends on:and groups steps into waves; - within each wave, runs steps concurrently when their write-
Files:sets are disjoint (read-only steps are always safe), dispatching each conflict-free batch as one message of parallelAgent(subagent_type="router-<model>", …)calls; - serializes overlapping writers (or isolates them in a worktree), then synthesizes + verifies after each wave.
plan-with-models owns execution — it does not hand off to
subagent-driven-development, which runs steps strictly sequentially. For
very large plans it can emit a Workflow script instead (opt-in).
Outside plan mode, an unmistakably multi-part prompt (numbered list,
"X and Y and Z", "for each…") is flagged fanout by the hook and handled by
Branch E of auto-model-routing with the same non-interference rules.
Retry / escalation policy
Workers can return Stopped: too complex for <tier>. Suggest re-dispatch to router-<higher>. The parent auto-retries one tier up when it sees
that signal, without asking. Implicit failures (errors, empty output)
trigger a same-tier retry-with-clearer-prompt, then escalate. Even Opus
failures fall back to inline handling with a visible note to the user.
See skills/auto-model-routing/SKILL.md → "Retry / escalation policy"
for the full state machine.
Disabling
- Temporary, per-prompt: append
#noshift. - Temporary, per-shell:
export CC_ROUTER_DISABLE=1. - Per-project:
{"disabled": true}in.claude/router.json. - Permanent:
/plugin disable auto-model-router@auto-model-router-mp. Plugin files remain installed; re-enable with/plugin enable.
Local / development install
If you're hacking on the plugin (not installing as a teammate via the marketplace), you can run it from a clone:
git clone https://github.com/<owner>/auto-model-router ~/.claude/plugins/auto-model-router
ln -sf ~/.claude/plugins/auto-model-router/skills/auto-model-routing ~/.claude/skills/auto-model-routing
ln -sf ~/.claude/plugins/auto-model-router/skills/plan-with-models ~/.claude/skills/plan-with-models
for m in haiku sonnet opus fable; do
ln -sf ~/.claude/plugins/auto-model-router/agents/router-$m.md ~/.claude/agents/router-$m.md
done
for c in route route-status router-report; do
ln -sf ~/.claude/plugins/auto-model-router/commands/$c.md ~/.claude/commands/$c.md
done
Then register all three hooks in ~/.claude/settings.json (mirror
hooks/hooks.json — see INSTALL.md → "Manual / non-marketplace install" for
the full block):
"hooks": {
"UserPromptSubmit": [{ "hooks": [{ "type": "command",
"command": "python3 $HOME/.claude/plugins/auto-model-router/hooks/auto-router.py", "timeout": 5 }] }],
"PreToolUse": [{ "matcher": "Agent", "hooks": [{ "type": "command",
"command": "python3 $HOME/.claude/plugins/auto-model-router/hooks/pre-agent-mark.py", "timeout": 2 }] }],
"PostToolUse": [{ "matcher": "Agent", "hooks": [{ "type": "command",
"command": "python3 $HOME/.claude/plugins/auto-model-router/hooks/post-agent-audit.py", "timeout": 3 }] }]
}
And run bin/install.sh for the cc-route PATH symlink.
The symlink dance and manual hook entries are needed only because you're
bypassing the marketplace install — and they don't auto-update when the plugin
gains new hooks/commands, so re-check hooks/hooks.json after upgrades.
Teammates using the marketplace flow don't do any of this.
Known limitations
- Can't switch the running session's model. Claude Code hooks do not expose a model-switch capability. The router-parent + workers pattern works around this by keeping the parent on whatever model you launched with and delegating the real work elsewhere.
- Classification is heuristic-first. Without
ANTHROPIC_API_KEY, ambiguous prompts fall back to "default Haiku at confidence 0.55" (which lands inaskband — you'll be prompted, cheap-and-confirm). With a key, the Haiku fallback classifier fires within ~1.5 s. - Subagents don't inherit your live conversation context — only your project's CLAUDE.md/AGENTS.md, working directory, and the prompt the parent passes. For deeply iterative sub-tasks (5+ back-and-forths on the same thread) you'll want to stay inline.
- Non-interference relies on declared
Files:. Parallel safety is proven from each step's declared write set. A step that writes a file it didn't declare can collide with a concurrent sibling — which is why the wave executor treats unlabelled writers as a bug and constrains each agent to itsFiles:in the prompt. When in doubt it serializes. - Plan mode is parent-detected, not hook-detected. The hook never
sees plan state, so plan-mode routing depends on the parent honoring
its own context (the
auto-model-routingskill instructs this).
Contributing
Issues and PRs welcome on the repo's GitHub page. Common areas to improve:
- Heuristic regex tuning (lots of false-negatives possible for niche
task verbs) — including the
fanoutdecomposition patterns. - A learned decomposer for Branch E fan-out (today it's heuristic; the
captured
group_id+ outcome data is the dataset for training one). - A streaming dispatch mode so workers' partial output can flow to the parent in real time (Claude Code limitation today).
License
MIT — see LICENSE.