Cap spend

agents cost is the observability half — what you already spent. agents budget is the enforcement half — it estimates a run's cost before it starts, can refuse to launch it, and for a local headless run can kill it mid-flight the moment a cap is crossed.

Configure caps

Add a budget: block to agents.yaml. It resolves project over user, same as every other section — a project's file overrides your user-global caps field by field. Every cap is in USD, and a cap is enforced only when set: an empty block is zero overhead.

# ~/.agents/agents.yaml or <repo>/agents.yaml
budget:
  currency: USD
  per_run: 5.00              # cap on a single run's estimated/actual cost
  per_day: 50.00              # cap on total spend today, across every agent
  per_project: 100.00         # cap on cumulative spend for this project
  per_agent:
    claude: 30.00
    codex: 20.00
  on_exceed: block             # block (refuse / kill) | warn (proceed, report)
  require_confirm_over: 1.00   # prompt before a run estimated at or above this

Pre-flight block

Every agents run prints an estimate and, under on_exceed: block (the default), refuses to launch when it would breach a cap — exiting non-zero so CI, headless runs, agents teams, and agents cloud all inherit the decision.

$ agents budget set per_run 0.01   # lowered here on purpose, to force a block
$ agents run claude "big refactor across the repo" --model claude-opus-4
[budget] est. $2.48 for this claude run (claude-opus-4, prompt size)
[budget] BLOCKED: estimated $2.48 exceeds per_run cap $0.01
Raise the cap in agents.yaml budget: or set on_exceed: warn to proceed.
$ echo $?
2

The estimate comes from recent ledger averages for the same agent, falling back to a prompt-size heuristic with no history yet. -y / --yes skips the interactive require_confirm_over prompt for scripts, but never skips a hard block — a breach blocks regardless of --yes.

The kill-switch (local headless runs)

For local, non-interactive (-p / --print / headless) agents run invocations, spend is parsed off the agent's stdout as it happens and checked against the caps live. The moment one is crossed the child is terminated — SIGTERM, then SIGKILL after 5s — and the run exits with a distinct code so a budget kill reads differently from a timeout or a crash.

$ echo $?
7   # budget kill — distinct from a normal failure (1) or a timeout

Interactive REPL sessions aren't live-killed — you own the TTY, and the pre-flight gate is your check. agents teams teammates and agents cloud dispatch are pre-flight-gated only for now; the live kill for those is a planned follow-up.

View and set caps

agents budget                      # caps + spend-to-cap bars (today + project)
agents budget --json               # machine-readable snapshot
agents budget set per_run 5        # write a user-global cap
agents budget set per_agent.claude 30
agents budget set on_exceed warn   # switch to warn-only, don't block

Budget  (on_exceed: block, currency: USD)
  project: /Users/you/code/rush-cli
  day:     2026-08-08

  per_run        (unset)
  per_day        $12.40 / $50.00       ▮▮░░░░░░░░
  per_project    $340.00 / $500.00     ▮▮▮▮▮▮▮░░░

Per-agent (today)
  claude         $9.10 / $30.00        ▮▮▮░░░░░░░

agents budget reports the effective merged config for the current directory; set writes the user-global layer, and a project's caps stay hand-edited in the repo's agents.yaml. Every run that produces token usage appends to a shared spend ledger — the same artifact agents cost reads for its rollups.

Related: Track spend, Where it goes, Run.