Dynamic Model Routing
March 16, 2026 · View on GitHub
Introduced in v2.19.0
Dynamic model routing automatically selects cheaper models for simple work and reserves expensive models for complex tasks. This reduces token consumption by 20-50% on capped plans without sacrificing quality where it matters.
How It Works
Each unit dispatched by auto-mode is classified into a complexity tier:
| Tier | Typical Work | Default Model Level |
|---|---|---|
| Light | Slice completion, UAT, hooks | Haiku-class |
| Standard | Research, planning, execution, milestone completion | Sonnet-class |
| Heavy | Replanning, roadmap reassessment, complex execution | Opus-class |
The router then selects a model for that tier. The key rule: downgrade-only semantics. The user's configured model is always the ceiling — routing never upgrades beyond what you've configured.
Enabling
Dynamic routing is off by default. Enable it in preferences:
---
version: 1
dynamic_routing:
enabled: true
---
Configuration
dynamic_routing:
enabled: true
tier_models: # explicit model per tier (optional)
light: claude-haiku-4-5
standard: claude-sonnet-4-6
heavy: claude-opus-4-6
escalate_on_failure: true # bump tier on task failure (default: true)
budget_pressure: true # auto-downgrade when approaching budget ceiling (default: true)
cross_provider: true # consider models from other providers (default: true)
hooks: true # apply routing to post-unit hooks (default: true)
tier_models
Override which model is used for each tier. When omitted, the router uses a built-in capability mapping that knows common model families:
- Light:
claude-haiku-4-5,gpt-4o-mini,gemini-2.0-flash - Standard:
claude-sonnet-4-6,gpt-4o,gemini-2.5-pro - Heavy:
claude-opus-4-6,gpt-4.5-preview,gemini-2.5-pro
escalate_on_failure
When a task fails at a given tier, the router escalates to the next tier on retry. Light → Standard → Heavy. This prevents cheap models from burning retries on work that needs more reasoning.
budget_pressure
When approaching the budget ceiling, the router progressively downgrades:
| Budget Used | Effect |
|---|---|
| < 50% | No adjustment |
| 50-75% | Standard → Light |
| 75-90% | More aggressive downgrading |
| > 90% | Nearly everything → Light; only Heavy stays at Standard |
cross_provider
When enabled, the router may select models from providers other than your primary. This uses the built-in cost table to find the cheapest model at each tier. Requires the target provider to be configured.
Complexity Classification
Units are classified using pure heuristics — no LLM calls, sub-millisecond:
Unit Type Defaults
| Unit Type | Default Tier |
|---|---|
complete-slice, run-uat | Light |
research-*, plan-*, complete-milestone | Standard |
execute-task | Standard (upgraded by task analysis) |
replan-slice, reassess-roadmap | Heavy |
hook/* | Light |
Task Plan Analysis
For execute-task units, the classifier analyzes the task plan:
| Signal | Simple → Light | Complex → Heavy |
|---|---|---|
| Step count | ≤ 3 | ≥ 8 |
| File count | ≤ 3 | ≥ 8 |
| Description length | < 500 chars | > 2000 chars |
| Code blocks | — | ≥ 5 |
| Complexity keywords | None | Present |
Complexity keywords: research, investigate, refactor, migrate, integrate, complex, architect, redesign, security, performance, concurrent, parallel, distributed, backward compat
Adaptive Learning
The routing history (.gsd/routing-history.json) tracks success/failure per tier per unit type. If a tier's failure rate exceeds 20% for a given pattern, future classifications are bumped up. User feedback (over/under/ok) is weighted 2× vs automatic outcomes.
Interaction with Token Profiles
Dynamic routing and token profiles are complementary:
- Token profiles (
budget/balanced/quality) control phase skipping and context compression - Dynamic routing controls per-unit model selection within the configured phase model
When both are active, token profiles set the baseline models and dynamic routing further optimizes within those baselines. The budget token profile + dynamic routing provides maximum cost savings.
Cost Table
The router includes a built-in cost table for common models, used for cross-provider cost comparison. Costs are per-million tokens (input/output):
| Model | Input | Output |
|---|---|---|
| claude-haiku-4-5 | $0.80 | $4.00 |
| claude-sonnet-4-6 | $3.00 | $15.00 |
| claude-opus-4-6 | $15.00 | $75.00 |
| gpt-4o-mini | $0.15 | $0.60 |
| gpt-4o | $2.50 | $10.00 |
| gemini-2.0-flash | $0.10 | $0.40 |
The cost table is used for comparison only — actual billing comes from your provider.