model-router

# model-router Decide which model each subtask deserves, instead of running everything on the most expensive one. Cheap tiers handle mechanical work; the expensive tier is reserved for where reasoning actually pays. ## Why this exists (evidence) - Community pattern: a Sonnet sub-agent for low-complexity work (e.g. DOCX processing) cut cost by ~50% vs running everything on the top model. The win exists but is hidden behind manual wiring. - Orchestration, not retraining, closes performance gaps: AI21 Maestro lifts a base model to top-tier SWE-bench Verified purely by allocating compute well. Routing is the cheap-side analogue: spend the expensive model only where it changes the answer. ## Routing policy (default) CHEAP tier (Sonnet, or Haiku for the most mechanical): - Code search, grep, file location, "where is X". - Boilerplate, scaffolding, renames, mechanical refactors with a clear pattern. - Doc writing, comments, changelog, formatting. - Reading/summarizing logs and tool output. - Generating test stubs and fixtures (not deciding what to assert). - Straightforward, well-specified single-file edits. EXPENSIVE tier (Opus): - Architecture and design decisions; choosing between approaches. - Hard debugging where the root cause is unknown. - Security-sensitive code (auth, crypto, payments, input handling). - Final verification / code review of a change. - Ambiguous requirements that need judgment. - Multi-file refactors where the reasoning spans modules. Rule of thumb: if the task has ONE obvious correct output, route cheap. If it needs judgment, route expensive. When unsure, the verification step stays on Opus even if the generation was cheap. ## How to apply In a Workflow (the main lever): - Set `model` per agent/stage. Cheap stages: `agent(prompt, { model: 'sonnet' })` or `'haiku'`. Hard stages: omit `model` to inherit Opus, or set explicitly. - Pattern: cheap fan-out (find/scan/draft) -> expensive judge/verify. Mirrors the canonical find -> verify pipeline. - Use `effort: 'low'` on cheap mechanical stages, higher only on the hardest verify/judge stages. Interactive (no Workflow): - Delegate a bounded cheap subtask to a Sonnet subagent via the Agent tool, then bring the result back to Opus for integration/verification. - Or switch the session model (/model) for a stretch of mechanical work, then switch back. ## Policy override State a policy in one line and follow it for the session, e.g.: - "Sonnet for everything except security code and final review." - "Haiku for search and docs, Opus for the rest." The override replaces the default table above for that session. ## Verification (prove the saving) Before claiming a cost win: run a representative pipeline (e.g. 5 mixed subtasks) twice, once all-Opus and once routed. Compare total output tokens AND quality (tests green / same correctness). The routing is only valid if quality holds. Report both numbers; do not assert a percentage you did not measure. ## Composes with - `best-tool` / `godmode` choose the best TOOL; model-router chooses the best MODEL for the subtask. - `context-warden` keeps each routed call's context lean, compounding the saving. ## Honest limits - A skill cannot silently change the main session model; routing is applied through Workflow per-stage model, subagent delegation, or an explicit /model switch. - The ~50% figure is a community datapoint on one workload, not a guarantee. Measure your own delta.