Cap what an agent can spend

agents budget estimates a run's cost before it starts and can refuse to launch it, then for a local headless run kills the process the moment live spend crosses a cap. Fifteen minutes to set one up and watch it fire.

Set a cap

Add a budget: block to your user-global agents.yaml, or write one straight from the CLI. Caps resolve project over user, and an unset cap costs nothing — the feature is dormant until you set one.

agents budget set per_run 5          # cap any single run at $5
agents budget set per_day 50         # cap total spend today, every agent
agents budget set per_agent.claude 30

agents budget

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

  per_run        $5.00
  per_day        $0.00 / $50.00        ▯▯▯▯▯▯▯▯▯▯

Per-agent (today)
  claude         $0.00 / $30.00        ▯▯▯▯▯▯▯▯▯▯

Watch it block a run

Set a cap low enough to breach on purpose, then run something real. The estimate prints before anything spawns, and a block exits 2 — distinct from a normal failure, so a script or CI step can tell the two apart.

$ agents budget set per_run 0.01
$ agents run claude "add input validation to the signup form"
[budget] est. $0.34 for this claude run (claude-sonnet-5, prompt size)
[budget] BLOCKED: estimated $0.34 exceeds per_run cap $0.01
Raise the cap in agents.yaml budget: or set on_exceed: warn to proceed.
$ echo $?
2

Raise the cap back to something real, or switch to warn-only so a breach reports instead of refusing to launch.

agents budget set per_run 5
agents budget set on_exceed warn   # proceed anyway, just report it

Watch it kill a headless run

The pre-flight estimate is a guess before the first token. For a local, non-interactive run (-p / --print), spend is parsed off the agent's stdout live and checked against the caps as it streams. Cross one and the child is terminated on the spot.

agents run claude -p "refactor the whole auth module" --model claude-opus-4
# ... spend crosses per_day mid-run ...
$ echo $?
7   # budget kill, not a timeout (124) or a crash (1)

An interactive REPL session is never live-killed — you own the TTY, and the pre-flight gate is the only check that applies. agents teams and agents cloud are pre-flight-gated only for now; the live kill for those is a planned follow-up.

Check the ledger

Every run that produces token usage appends to a shared, append-only spend ledger — the same artifact agents cost reads for its rollups, so a kill still leaves an accurate record of what actually burned before it was stopped.

agents budget --json   # effective caps + spend-to-cap, for a dashboard
agents cost --since today --by agent