Model Routing

Model Routing is part of the org-level pipeline configuration (Settings → Agents). It lets you pin a specific Claude model to each combination of task type and complexity tier, so cheaper models handle simple work while higher-capability models handle complex work. For a step-by-step walkthrough of how to configure and verify routing, see the Tune Model Routing and Cost Caps guide.

Fields

Enable model routing

Property	Value
Config key	model_routing.enabled
Default	false (off)

Master switch for task-type × complexity-tier model routing. When disabled, the routes table and override field are ignored and Colony uses the per-role models configured under Settings → Agents › Models (the claude.models.* fallbacks) for every task. When enabled, Colony consults the global override and routes table before each agent invocation.

Note

Disabling model routing does not clear the routes table or the override field — the values are preserved so you can re-enable routing later without reconfiguring the matrix.

---

Global override

Property	Value
Config key	model_routing.override
Default	empty (inactive)

Global force-model kill-switch. When non-empty, this model is used for every Colony task — analyze, develop, review, merge, and plan — regardless of task type, complexity tier, or the per-task matrix below. It unconditionally overrides all other routing logic and is checked first before any other routing rule.

Use this as an emergency brake (for example, to force a cheaper model during a cost spike) or for a temporary experiment. Clear the field to restore normal routing.

Caution

The global override applies unconditionally to every task until the field is cleared. Setting it to a low-capability model will affect all pipeline work, including large-tier development and review tasks.

See also: Cost & Budget concepts — the three budget controls for how the force-model override interacts with daily (max_daily_usd) and monthly (cost_budget.monthly_usd) spend limits.

---

Per-task, per-tier model overrides

Property	Value
Config key	model_routing.routes[task][tier]
Default	empty (all cells fall through)

A 5 × 3 matrix where rows are task types and columns are complexity tiers. Each cell specifies the Claude model to use for that task-type / tier combination.

Task types (rows): analyze · develop · review · merge · plan

Complexity tiers (columns): small · medium · large — assigned by the analyzer agent based on estimated issue scope.

Empty cells fall through to the next level in the resolution precedence chain (see Resolution precedence below). You only need to fill in the cells you want to override; omitting a cell is equivalent to “inherit from the role model.”

Resolution precedence

When Colony selects a model for an agent invocation, it walks the following chain from highest to lowest priority and uses the first non-empty value:

1. model_routing.override — global kill-switch; if set, all other levels are skipped.
2. model_routing.routes[task][tier] — the per-task, per-tier matrix cell for the current task type and complexity tier (only consulted when model_routing.enabled is true).
3. claude.models.<role> — the per-role model configured under Settings → Agents › Models.
4. Foundry pin_models — the model pinned in the active foundry deployment.
5. Built-in default — Colony’s hard-coded model default.

Role permissions

Action	Required role
View model routing configuration	Owner or Admin
Save model routing configuration	Owner or Admin

Model routing is part of the org-level pipeline configuration saved via PUT /api/orgs/:orgId/pipeline/config, which requires the owner or admin role (requireOrgMembership('owner', 'admin')).

Merge precedence

Org-level model routing values (tenants.config.model_routing.*) can be overridden at the repository level. The effective value for any field follows:

repo_configs.field ?? tenants.config.field ?? default

Repository-level overrides are configured per-repo under each repository’s Settings tab. Omitting a field at the repo level inherits the org default.