convez.ai
SkillAutomaçãoAvançado
IuriiTurok

Auto Model Router

IuriiTurok/auto-model-router

Classifica prompts e roteia entre Haiku/Sonnet/Opus com paralelismo seguro

Ver no GitHub
InicialPluginScore · de 0 a 100

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

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.3.0
Issues abertas
1
Contribuidores
2

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:

  1. Cost efficiency — estimated $ saved by routing work to the cheapest sufficient model (vs an all-Opus counterfactual).
  2. Quality — user-correction rate, router-delegated vs inline. The router cohort must not be worse.
  3. 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 via Agent and reports the worker's result. No interactive step.
  • ask (0.60–0.75): parent calls AskUserQuestion with 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

MechanismEffect
#noshift in the promptSkip routing entirely for this prompt (opt-out, tier=optout).
#noroute in the promptAlias for #noshift.
#model=opus (or sonnet/haiku/fable)Force-route to that tier; confidence 1.0, band=auto.
Env CC_ROUTER_DISABLE=1Disable the hook globally for the shell.
Env CC_ROUTER_AUTO_THRESHOLD=0.9Raise/lower the auto-delegate cutoff (default 0.75).
Env CC_ROUTER_ASK_THRESHOLD=0.6Raise/lower the ask cutoff (default 0.60).
Env ANTHROPIC_API_KEYEnables the Haiku fallback classifier for ambiguous cases. Without it, low-confidence prompts default to Sonnet/ask.
Project .claude/router.jsonPer-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. /route bypasses by deleting the entry.
  • Audit log: ~/.claude/cache/router/audit.jsonl. One line per decision; includes prompt SHA prefix, decision, outcome (injected / silent). /route-status reads 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:

  1. requires every step to carry Model:, Effort:, and Files: tags;
  2. builds a dependency DAG from Depends on: and groups steps into waves;
  3. 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 parallel Agent(subagent_type="router-<model>", …) calls;
  4. 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 in ask band — 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 its Files: 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-routing skill 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 fanout decomposition 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.

Ver o original no GitHub

Bom para

Relacionados