Skip to content

Tune Model Routing and Cost Caps

Colony has three separate spend controls: role model defaults, optional task-and-tier routing, and cost limits. Measure a representative baseline before changing them so that lower spend is not confused with a change in issue mix.

Model-routing rows are analyze, develop, review, merge, and plan; columns are small, medium, and large. Complexity begins with analysis and may be adjusted by routing signals such as decomposition or review history.

Resolution is:

  1. model_routing.override, when set;
  2. a matching model_routing.routes cell, when routing is enabled;
  3. the configured model for the corresponding agent role and its built-in fallback.

The default is not one universal highest-capability model: defaults vary by role and, for development, can vary by scaling tier. Tasks such as external review are normalized to the appropriate routing row; tasks with no routing row use their role fallback.

model_routing:
enabled: true
routes:
develop:
small: claude-sonnet-5
large: claude-opus-5-5
review:
small: claude-sonnet-5

Empty cells inherit. Use provider-supported model identifiers for your deployment.

  • claude.max_cost_per_issue limits accumulated spend for one issue. Once enforcement detects the limit, further autonomous work is blocked. A final provider invocation can make recorded spend slightly exceed the configured value.
  • max_daily_usd limits aggregate spend for the UTC day. The Worker claim loop reserves budget_headroom_pct below that number, so the effective stop threshold is lower than the headline cap. Work can resume after the next UTC reset or after the limit is raised.

Omit claude.max_cost_per_issue for no per-issue limit. Omit max_daily_usd and the $50 default daily cost cap applies. YAML null turns the daily ceiling off at runtime, but colony check fails its config stage because the schema expects a number, so do not use it unless you mean to run without a ceiling.

  1. Open Standards → Settings (/standards/settings).
  2. Configure role defaults under Models and tier-specific development behavior under Scaling.
  3. Enable Model Routing only for task/tier cells that should override those defaults. Treat the global override as a temporary force-model control.
  4. Decide whether to keep Fall back to another model family on model-specific quota limits on (the default, model_routing.quota_fallback). Leaving it on keeps work flowing during quota exhaustion. Turning it off keeps every task on the chosen model, at the cost of delays. See Quota fallback.
  5. Under Costs, set the per-issue limit and, if you want, the budget headroom. Leave the per-issue field blank to omit that limit. The daily limit (max_daily_usd) is the daily cost cap. It is shown read-only there, administrators change it in Budgets with a reason, and it defaults to $50.
  6. Save the configuration. New task invocations use the updated effective settings after configuration propagation.

Repository settings currently offer only selected per-role model overrides. They are not a full per-repository copy of the task/tier routing matrix. Repository monthly caps and the monthly ceiling are set in Operations → Settings (see Dashboards), and a monthly budget should not be confused with max_daily_usd.

Run several representative issues; a single issue is too noisy for a routing conclusion. In Colony Cloud, compare cost by model over the same window and repository mix as the baseline; see Cost & Budget (Cloud). In self-hosted telemetry, inspect model-resolution trace phases and cost events rather than searching for a model_selected log event—the runtime trace phase is model_resolved.

Also watch quality signals: clarification rate, review cycles, reimplementation, failures, and time to completion. A cheaper route that causes more retries may cost more overall.