Model routing

The routing block in settings.json wires up three behaviours. All are opt-in, and all resolve model ids/labels against your models list (or the startup model) the same way /model <query> does.

{
  "model": "claude-sonnet-5",
  "routing": {
    "failover": ["claude-sonnet-5", "qwen3-coder"],
    "summaryModel": "qwen3-coder",
    "planModel": "claude-opus-5"
  },
  "models": [
    { "provider": "openai-compatible", "model": "qwen3-coder", "baseURL": "http://localhost:11434/v1" },
    { "provider": "anthropic", "model": "claude-opus-5" }
  ]
}

POLYGLOT_ROUTING_FAILOVER (comma-separated), POLYGLOT_SUMMARY_MODEL, and POLYGLOT_PLAN_MODEL are the environment equivalents.

Failover

When the active model errors out (network error, 5xx, auth failure) or stops producing valid tool calls in the middle of a turn, the turn continues on the next model in failover instead of stopping. You see a notice in the transcript and the status bar flips to the new model.

• The failed model’s last (malformed) reply is dropped, so it can’t prime the fallback to imitate it.
• The switch is sticky for the rest of the session - /model puts you back.
• The session’s saved header keeps the model you started on, so a later --resume retries that model first.
• Each model in the chain is tried at most once per turn; if they all fail the turn stops as it would have before.
• -p --output-format json reports any switches in a fell_back_to array.

A useful pairing is a hosted model as the primary with a local one as the backup (or vice-versa) - you keep working through an outage on either side.

Failover is not the smart, per-message model routing some tools offer. It reacts to a concrete failure, it doesn’t guess which model a request “should” use.

Summary model {#summary-model}

summaryModel runs /compact and automatic compaction on a different model. Compaction is bulk summarisation of old turns - a cheap model does it well, and it keeps the spend off your main model. The /compact note tells you which model was used.

Plan model

planModel runs plan-mode turns on a dedicated model - e.g. a stronger reasoning model for planning, a cheaper one for the edits. It applies per turn while you’re in plan mode and is restored afterward.

Switching models manually with /model disables planModel auto-routing for the rest of the session, on the assumption that an explicit choice should win.