Cost & budget

Because agents run unattended, cost is a first-class control input — not an afterthought. Every claude call reports total_cost_usd, which is appended to the cost ledger with running totals; budgets cap autonomous spend and actually stop the loop when hit.

The ledger

Every LLM call writes one line to logs/cost/ledger.jsonl — its tokens and USD — with running totals kept overall, per-day, and per-month. Consultant (sub-agent) cost rolls up to the agent that hired it; a delegated task’s cost rolls up to its own assignee.

Where you see it:

• Dashboard — the Status panel shows today’s and this month’s spend.
• Programmatically — GET /api/metrics exposes the same numbers.

Budgets

Budgets cap spend. There are four kinds; set any subset — an omitted field means no cap.

cap	env var	behavior when hit
totalUsd (lifetime)	BUDGET_TOTAL_USD	the org halts for good
dailyUsd	BUDGET_DAILY_USD	skip cycles until the day rolls over
monthlyUsd	BUDGET_MONTHLY_USD	skip cycles until the month rolls over
perCycleUsd	BUDGET_PER_CYCLE_USD	logs a warning; halts new dispatch mid-cycle

Budget is re-checked before each task and between drain passes, so a cap is real, not a start-of-cycle-only gate a single cycle could blow past.

Setting a budget

Three places, in increasing precedence — a CLI flag beats an env var beats the file:

# in QUORUM.md
- budget: { "totalUsd": 50, "dailyUsd": 10, "monthlyUsd": 40, "perCycleUsd": 2 }

# environment
BUDGET_DAILY_USD=5  BUDGET_MONTHLY_USD=100  BUDGET_PER_CYCLE_USD=0.5  quorum

# CLI — the lifetime cap; halt for good at $25 spent
quorum --budget 25

A bare number as budget in a file means { "totalUsd": n }.

Per-session ceilings

Two more limits keep a single agentic run from blowing the cycle cap:

• The runtime passes the remaining per-cycle budget as the binary’s --max-budget-usd on every task run, so one run stops itself before it can exceed the cycle cap.
• A hired (or configured) agent can carry its own maxBudgetUsd in its provider config as a standing per-run cap — a natural way to keep a junior role cheap.

### Engineer
- provider: { "type": "claude", "model": "claude-sonnet-4-6", "maxBudgetUsd": 2 }

A stop is immediate

When a hard cap is reached — or you stop the org — the current cycle’s work is aborted immediately, killing in-flight claude children. Spend halts at once, not at the next tick. See the cycle.

Choosing a model and effort to control cost

The cheapest lever is the brain itself. Put a top model at high effort on the roles that need judgment, and a cheaper model at lower effort on routine execution — see The brain. Combined with maxBudgetUsd per role and a lifetime --budget, you can let an org run unattended with a firm ceiling on what it can ever cost.