# Run Budget Guard

> Spending caps for one AI agent run, shared by every sub-agent. Free watch-only mode tracks spend and drafts a weekly report of runs that went over; Pro enforces the cap with a clear STOP before the next model or tool call. $9 a month.

## Connect
- MCP (streamable HTTP): https://budget.cloudforbots.com/mcp
- Claude Code: `claude mcp add --transport http run-budget-guard https://budget.cloudforbots.com/mcp`
- REST: `POST https://budget.cloudforbots.com/api/run/<tool>` with JSON args. OpenAPI: https://budget.cloudforbots.com/openapi.json
- Auth: optional `Authorization: Bearer <key>`. Free key: `POST https://budget.cloudforbots.com/api/key`

## Pricing
- Free: 500 calls/day (daily, not a trial). No signup.
- Pro: $9/month, 50000 calls/day: https://pay.instaloops.com/b/8x2fZh0Ped799P94Kr83C3w
- Bring your own model. Works with Claude, Codex, ChatGPT, Grok Bot.

## Tools
### open_budget
Open a hard budget for one agent run before it starts: max dollars, tokens, calls and/or wall-clock seconds. Returns a handle. Give the handle to every sub-agent; they all draw from the same ledger, so one runaway loop or fork cannot exceed the run cap.
Inputs: `label` (string), `max_usd` (number), `max_tokens` (integer), `max_calls` (integer), `max_seconds` (integer), `ttl_hours` (integer), `mode` (string)

### reserve
Call BEFORE each model call, tool call or sub-agent spawn with your estimate. Returns allowed=true and deducts it, or allowed=false with the limit that tripped. When allowed is false, stop, do not retry, and return your partial result to the user. Atomic, so parallel sub-agents cannot both slip under the cap.
Inputs: `handle` (string, required), `usd` (number), `tokens` (integer), `calls` (integer), `note` (string)

### record
After a call, report the actual usage minus what you reserved (positive if it cost more, negative to give back an overestimate). Keeps the ledger honest without blocking.
Inputs: `handle` (string, required), `usd` (number), `tokens` (integer), `note` (string)

### weekly_report
Draft a plain-English report of the last 7 days for your key (or IP): runs, spend, runs that went over their cap, and dollars spent after a cap would have stopped them. Read-only; sends nothing. Show it to your user.
Inputs: none

### budget_status
See spend vs limits, remaining budget, whether the run is stopped and why, and the last 20 ledger events. Set close=true when the run finishes.
Inputs: `handle` (string, required), `close` (boolean)

### usage_and_upgrade
Usage today + upgrade link (not metered).

## FAQ
### What problem does this solve?
Agent loops and sub-agent forks can burn millions of tokens in one run before anyone notices. Provider caps are monthly or org-wide, and SDKs report usage after the run. Run Budget Guard gives one run a hard cap that every sub-agent shares, checked before each call. Start free in watch-only mode to see what your runs actually spend.

### How does my agent use it?
Call open_budget at the start with max_usd, max_tokens, max_calls and/or max_seconds. Before every model call, tool call or sub-agent spawn, call reserve with your estimate. If allowed is false, stop and return the partial result. Optionally call record with the actual usage to keep the ledger exact.

### Does it work across sub-agents running in parallel?
Yes. Pass the handle to each sub-agent. Every reserve is an atomic check-and-deduct on one ledger row, so eight parallel calls against a cap of five calls allow exactly five.

### Who estimates the cost?
Your agent does. Run Budget Guard does not see your prompts or proxy your model traffic; it only counts the numbers you send. Use your provider's published prices for the estimate and record to correct it.

### What happens when a limit trips?
In free watch-only mode nothing is blocked: reserve returns would_block=true and the weekly report counts the spend past the cap. With Pro in enforce mode the run is marked stopped with the reason (max_usd, max_tokens, max_calls, max_seconds) and every later reserve returns allowed=false, so a looping agent cannot creep past the cap.

### What is in the weekly report?
Call weekly_report: runs in the last 7 days, total dollars, tokens and calls, how many runs went over their cap, and how much was spent after a dollar cap would have stopped them. It is a draft your agent shows you; nothing is sent or changed.

### What does it cost?
Free: watch-only shadow mode, 500 checks a day, 10 open runs, weekly report, handles last 24 hours. Pro is $9 a month: enforcing caps, 50,000 checks a day, 200 open runs, handles up to 7 days. You get your Pro key on screen right after paying.

Publisher: Supa Humans (https://supahumans.ai). Marketplace: https://botrecipe.com/tools/