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

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 pricing
• model — the model identifier used for the call
• recorded_at — the UTC timestamp of the invocation
• owner / 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. There is no sampling or approximation — if an invocation happened, it is recorded.

The figures reflect actual token consumption by Colony’s agents — the analyzer, developer, reviewer, merger, and planner. They do not include seat charges, subscription fees, or any cost that does not involve LLM token usage.

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)

Each repository can have a budget_cap_usd value set in its configuration. This is a reporting control, not a runtime enforcement gate. Colony Cloud sums budget_cap_usd across all repositories in a tenant to produce an aggregate monthly budget figure. That aggregate appears in burn-rate and projected-exhaustion reporting — if current-month spend is trending toward the aggregate cap, the projected exhaustion date is calculated from the trailing burn rate.

budget_cap_usd does not by itself stop Workers from claiming new tasks. It is an operator-supplied target used to make spend projections meaningful.

Daily spend ceiling (max_daily_usd + budget_headroom_pct)

max_daily_usd is a top-level configuration field (default: 50) that sets a hard daily spending ceiling per UTC day. 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 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.

Setting max_daily_usd to null disables the daily ceiling entirely. 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)

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 spend is manually reset or the next billing cycle begins.

cost_budget.monthly_usd is distinct from the monitoring section’s CostAlertThreshold.monthly_usd. 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 (Cloud)	Reporting target for burn-rate and exhaustion projections
max_daily_usd + budget_headroom_pct	Global, per UTC day	Enforced — stops Workers when effective cap is reached
cost_budget.monthly_usd	Per tenant, monthly	Enforced — stops Workers when monthly spend is exhausted
CostAlertThreshold.monthly_usd (monitoring)	Global	Alerting only — sends notification, does not stop work

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

The monthly cost projection takes two operator-supplied inputs:

• throughputPerDay — the expected number of issues completed per day
• mix — 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 × 30

Low 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

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. 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) × globalValue

A 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

• Configuration Schema — max_daily_usd, budget_headroom_pct, and cost_budget.monthly_usd field definitions
• Metrics — pipeline metric definitions including cost-related signals