Budget & cost

Track spend per task, per day, per workspace. Hard caps stop runaway runs.

Budget modes

Set in Settings → Budget → Mode:

ModeBehavior
EconomyLocal-first. Aggressive caching. Small context windows. Cheap router models. Cloud only when local fails.
Balanced (default)Standard planner. Tiered context. Mid-tier models with selective premium.
DeepBroad context windows. Premium models for reasoning + coding. Full subagent mesh.

Mode affects model selection, context budget, and which subagent roles run.

Caps

Set in Settings → Budget → Policy:

  • Max cost per task — hard ceiling per agent run.
  • Max cost per day — workspace-wide daily ceiling.
  • Max files per task — hard ceiling on files staged in one run.
  • Max context bytes — caps the prompt size sent to the model.

Plus toggles:

  • Ask before premium — when the router wants a premium model, pause for confirmation.
  • Local-first — try local symbol index + LCS before calling cloud APIs.
  • Cloud fallback — if local fails or is too uncertain, fall back to cloud.
  • Stop if over-budget — hard stop. Default on.

Live cost preview

The planner shows ~$0.0012 → in: 412 / out: 280 → session: $0.18 / $5.00. Updates as you type. When you exceed the cap, it goes red and Send is disabled.

This is POST /api/budget/estimate — no model tokens spent.

Today meter

The Budget panel shows usage vs cap for today, broken down by:

  • Tasks (count + cost).
  • Cache hits (count + savings).
  • Routes (which model tier got the most spend).

Cache stats

The router caches semantic context, symbol lookups, and even some plan outputs. Stats panel shows:

  • Entry count.
  • Hit rate %.
  • On-disk size.
  • Clear button (wipes cache for this workspace).

Receipts breakdown

Each row in the Receipts tab is expandable to show the cost detail:

  • Input tokens.
  • Output tokens.
  • Per-model breakdown.
  • Reasoning chains spent.
  • Cache reuse savings.

The "Why did this cost this much?" disclosure is the audit trail for spend.

Ledger export

GET /api/budget/ledger?ws_id=… returns per-day per-task cost history as JSON. Useful for analytics or chargeback in team contexts.

[
  { "day": "2026-04-25", "tasks": 12, "cost_usd": 0.42 },
  { "day": "2026-04-24", "tasks": 8, "cost_usd": 0.18 }
]

Hitting the cap

When the daily cap is hit:

  • New runs are blocked with: Daily budget exceeded ($5.00 / $5.00). Increase in Settings or wait until midnight UTC.
  • Inline diff edits are also blocked.
  • Cancel/rollback operations are still allowed (they're free).

Increase the cap in Settings to unblock immediately.