Cost & Budget
Colony records the actual LLM token cost of every agent invocation. This page explains how those records accumulate into the figures you see in reports, what each configuration control does (and does not) enforce, and what the forward-looking projection numbers assume.
How spend is measured
Section titled “How spend is measured”Every LLM call made by a Colony agent produces a discrete cost event. Each event carries:
cost_usd— the USD cost of that invocation, derived from token counts and model pricingmodel— the model identifier used for the callrecorded_at— the UTC timestamp of the invocationowner/repo/issue_number— the repository and issue the call is attributed to
These events are stored in the cost_events table, exposed through the v1_cost_events view. Total spend for any time window is the sum of cost_usd over all matching cost events in that window. Cost events are not sampled, but they are not a guaranteed complete ledger: a Worker retries an event it could not save and can drop it after repeated failures, a run stopped at its deadline records an estimate based on elapsed time, and a gateway model Colony cannot price reports zero cost.
The figures reflect actual token consumption by Colony’s agents — the analyzer, developer, reviewer, merger, and planner. Repository-scoped spend, such as the Strategist’s, has no issue number and is not in v1_cost_events. The figures do not include seat charges, subscription fees, or any cost that does not involve LLM token usage.
The three budget controls
Section titled “The three budget controls”Colony has three distinct budget mechanisms. They operate at different scopes, enforce different things, and should not be conflated.
Per-repo monthly budget cap (budget_cap_usd)
Section titled “Per-repo monthly budget cap (budget_cap_usd)”Each repository can have a budget_cap_usd value set in its configuration. This is an enforced per-repo monthly cap. On each poll, Colony compares the repo’s month-to-date spend with its cap and stops claiming new work for that repo once the cap is reached. The tenant ceiling (cost_budget.monthly_usd) is compared with the tenant’s month-to-date spend across all its repos, and the repo cap with that repo’s spend alone. A repo’s effective ceiling is the lower of the two. Both are authored in Operations → Settings.
The budget overview reports against the tenant ceiling; repo caps are not summed.
Daily spend ceiling (max_daily_usd + budget_headroom_pct)
Section titled “Daily spend ceiling (max_daily_usd + budget_headroom_pct)”max_daily_usd is a top-level configuration field (default: 50), the daily cost cap, that sets a hard daily spending ceiling per tenant per UTC day. It is shown read-only in the dashboard, and administrators change it in Budgets, with a reason. The effective stop threshold is:
effectiveCap = max_daily_usd × (1 − budget_headroom_pct / 100)budget_headroom_pct defaults to 10, so by default the effective stop threshold is 90% of max_daily_usd. The headroom exists because multiple Workers can check the daily spend simultaneously and start tasks that each push spend a little past the headline number — the reservation absorbs that overage.
When the effective cap is reached, Workers stop claiming new tasks for all of that tenant’s repos until the UTC calendar day resets at midnight. Issues remain in their current pipeline state and resume automatically on the next UTC day. No manual intervention is required.
In self-hosted YAML, max_daily_usd: null turns the daily ceiling off at runtime, but colony check fails its config stage because the schema expects a number. In Colony Cloud the daily ceiling cannot be turned off; clearing the value restores the default. Setting budget_headroom_pct to 0 removes the reservation and uses the exact max_daily_usd value as the stop threshold.
Monthly tenant enforcement threshold (cost_budget.monthly_usd)
Section titled “Monthly tenant enforcement threshold (cost_budget.monthly_usd)”Under a tenant block in colony.config.yaml, cost_budget.monthly_usd sets a monthly spend ceiling for that tenant. This is an enforcement control: when the tenant’s tracked monthly spend reaches the limit, Workers skip all repos belonging to that tenant and post a single notification comment. Work resumes when the next UTC calendar month begins or when the limit is raised.
cost_budget.monthly_usd is distinct from agents.monitor.cost_alert_threshold.monthly_usd (the legacy top-level monitoring: block is deprecated and merged into agents.monitor). The monitoring alert threshold sends a notification when spend crosses a level; it does not stop work. The tenant cost_budget.monthly_usd stops work.
Summary of enforcement roles:
| Control | Scope | Role |
|---|---|---|
budget_cap_usd | Per repo, monthly | Enforced — stops new work on that repo when its month-to-date spend reaches the cap |
max_daily_usd + budget_headroom_pct | Per tenant, per UTC day | Enforced — stops Workers for that tenant when effective cap is reached |
cost_budget.monthly_usd | Per tenant, monthly | Enforced — stops Workers when monthly spend is exhausted |
agents.monitor.cost_alert_threshold.monthly_usd | Global | Alerting only — sends notification, does not stop work |
Projection assumptions and their limits
Section titled “Projection assumptions and their limits”Colony can project future spend and estimate the cost of a specific new issue. Both features use historical cost data, but they make different assumptions.
Monthly cost projection
Section titled “Monthly cost projection”The monthly cost projection takes two operator-supplied inputs:
throughputPerDay— the expected number of issues completed per daymix— the expected proportion of small, medium, and large issues (must sum to 100)
For each complexity tier, Colony computes the historical average cost per completed issue (avgCostUsd) from past cost events. The projected monthly cost for a tier is:
avgCostUsd × mixFraction × throughputPerDay × 30Low and high bands use the P25 and P75 percentiles of historical per-issue cost instead of the average. The total projection sums across all three tiers.
What this assumes and why it is approximate:
- The projection uses raw historical averages for each tier — it does not blend with any cross-tenant baseline. If a repo has few completed issues in a tier, the average for that tier may reflect a small and unrepresentative sample.
- Future issues are assumed to resemble past ones in scope and complexity. Atypical past issues (unusually large refactors, very simple bug fixes) skew the per-tier average.
- The throughput and mix are operator assumptions. Colony does not infer them from pipeline state or historical throughput.
- The 30-day horizon is a fixed multiplier. It does not account for calendar effects, planned work pauses, or team capacity changes.
- P25/P75 bands are ranges, not confidence intervals. Issues with high cost variance will produce wide bands; a narrow band with few samples may still be unreliable.
Per-issue estimate
Section titled “Per-issue estimate”The per-issue estimate endpoint produces a cost estimate for a single new issue based on a description and optional complexity hint. It uses P10/P50/P90 percentiles of completed-issue cost for the matching repo and complexity tier.
When a repo has few completed issues, the local percentile figures are unreliable. The global baseline is aggregated from cost data across all tenants in the same Pipeline Store. In Colony Cloud, each customer organization has its own store, so that means your own data only. To compensate, the estimate blends local repo history with a cross-tenant global baseline:
localWeight = min(sampleSize / 30, 1.0)blendedPercentile = localWeight × localValue + (1 − localWeight) × globalValueA repo with 30 or more completed issues of the matching tier uses its local history exclusively. A repo with no history uses the global baseline entirely. Repos between those extremes interpolate.
This blending applies only to single-issue estimates. The aggregate monthly cost projection does not blend with a global baseline — it uses only tenant-scoped history.
Going deeper
Section titled “Going deeper”- Configuration Schema —
max_daily_usd,budget_headroom_pct, andcost_budget.monthly_usdfield definitions - Metrics — pipeline metric definitions including cost-related signals