# Run Budget Guard

> A hard spending cap for one AI agent run, shared by every sub-agent. Your agent checks before each model or tool call and gets a clear STOP when the run hits its dollar, token, call or time limit. Free 500 checks a day, then $9 a month.

- MCP (streamable HTTP): https://budget.botrecipe.com/mcp
- REST: POST https://budget.botrecipe.com/api/run/<tool> with JSON args
- Install (Claude Code): claude mcp add --transport http run-budget-guard https://budget.botrecipe.com/mcp
- Codex / ChatGPT / Grok Bot: add a remote MCP server with URL https://budget.botrecipe.com/mcp
- Skill file: https://budget.botrecipe.com/SKILL.md
- Catalog entry: https://budget.botrecipe.com/tool.json
- Marketplace: https://botrecipe.com/tools/run-budget-guard/

## Pricing
- Free: 500 calls/day, no key needed (resets daily; not a trial)
- Pro: $9/month, 50000 calls/day: https://pay.instaloops.com/b/8x2fZh0Ped799P94Kr83C3w
- Bring your own model: no LLM runs inside this tool.

## 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.
- 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.
- 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.
- 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.
- usage_and_upgrade: Usage today + upgrade link (not metered).

## More
- Full docs: https://budget.botrecipe.com/llms-full.txt
- Markdown page: https://budget.botrecipe.com/index.md
- OpenAPI: https://budget.botrecipe.com/openapi.json

## 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.
- 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? 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. Open a new budget to continue.
- What does it cost? Free: 500 checks a day, 10 open runs, handles last 24 hours. Pro is $9 a month: 50,000 checks a day, 200 open runs, handles last up to 7 days. You get your Pro key on screen right after paying.