Model Routing

A tier is an intent, not a capability floor. It describes what kind of work the caller thinks it is doing, not how powerful the model must be. This matters because it lets you change providers and model generations without touching any code that asks for coding — the intent is stable, only the binding moves.

This indirection is the reason skills declare tier: coding instead of a model ID. A skill authored in 2024 still works in 2027 without edits; the operator just updates the router.

When more than one source wants to set the tier, the router resolves in this fixed order (highest wins):

1. User override — /model openai/gpt-5.1 or /tier coding command from the operator, per turn.
2. Skill override — tier: coding in the skill frontmatter, for the duration of the skill.
3. Dynamic escalation — the runtime upgrades a turn from balanced to a higher tier when it detects the request needs it. Only active when dynamicTierEnabled is true.
4. Default — balancedModel.

Configure in Settings → Model Router or in preferences/model-router.json. Model IDs use the provider/model format; the provider prefix must match a key in the LLM providers section.

{
  "modelRouter": {
    "routingModel": "openai/gpt-5.2-codex",
    "balancedModel": "openai/gpt-5.1",
    "smartModel": "anthropic/claude-sonnet-4-20250514",
    "codingModel": "openai/gpt-5.2",
    "deepModel": "anthropic/claude-opus-4-20250514",
    "dynamicTierEnabled": true,
    "temperature": 0.7
  }
}

If you are setting this up for the first time and do not yet know what load looks like, use the following and adjust after a week of real traffic.

• balanced — mid-size general model from your primary provider (for example gpt-5.1). Most turns land here.
• coding — a code-specialized model from the same provider if available, otherwise the same as balanced.
• smart — leave unset initially; dynamic escalation will promote turns that need it into balanced. Set a real value only after you see turns that should have been escalated.
• deep — only set when you have a concrete use case (research skill, long-horizon auto mode). An unset deep tier falls back to smart, then balanced.
• dynamicTierEnabled — true. Turn it off only if you need strict cost control and want every turn to stay at its declared tier.

Dynamic escalation uses the routingModel (a small, fast model) to classify the incoming turn and decide whether to promote it. Escalation never downgrades — a user or skill override always wins.

Skills that need a specific tier should declare it in frontmatter. See Skills for the full SKILL.md contract.