claude-code, codex, api15 minintermediateverified: claude-fable-5, 2026-07
SOP: Cap an agent run's spend before it runs away
When done, long runs stop (or wrap up cleanly) at a budget you set instead of
burning your window/wallet. 15 minutes; needs Node (for ccusage) or an API key
with limits access.
Before you start
- [ ] Subscription plan:
npx ccusage@latest blocksruns and shows your
current 5-hour block. (API users: skip to step 4.)
Steps
- Set the hard backstop (API users / Console): console.anthropic.com →
- Give the agent a budget contract. In the task prompt (or /goal):
- Make it mechanical, not honorary (Claude Code): the
+500k-style token - (API harnesses) wrap the loop: count
usage.output_tokensper call,
Billing → Limits → monthly cap.
✓ Check: the cap shows in the console.
"Budget: ~N hours of my 5-hour window / ~X tokens. Check burn with
npx ccusage@latest blocks --json at every checkpoint; at 80% of budget,
stop adding scope and wrap up: checkpoint file, commit, summary."
✓ Check: the agent's first checkpoint report quotes actual ccusage numbers.
target in a prompt is enforced by workflows; for plain sessions, put the
ccusage check into the loop skill you use (window-surfer's /goal already
does this).
✓ Check: a test run's log shows a burn check between tasks.
accumulate, and hard-stop the loop past the threshold — abort is the
guardrail; the model's cooperation is just comfort.
✓ Check: a dry run with a tiny threshold (e.g. 5k) aborts as expected.
Verify the whole thing
Start a deliberately oversized task with a small budget. Expected: work →
burn checks in the log → clean wrap-up near 80% → checkpoint file exists →
nothing ran past the cap.
Rollback
Remove the budget clause from prompts/skills; delete the console cap. ccusage
installs nothing permanent (npx).
When it breaks
| Symptom | Cause | Fix |
|---|---|---|
| ccusage shows nothing | no local transcript data (fresh machine/plan) | fall back to wall-clock budgeting via date (see /goal) |
| Agent ignores the 80% rule | budget stated once, buried | repeat it in the checkpoint file header the agent re-reads |
| API loop overshoots | counting input+output against an output-sized cap | decide which you're capping; count that consistently |
Changelog
- 0.1.0 (2026-07-04) — initial, verified on Claude Fable 5.
One email when a pack ships or gets re-benchmarked on a new model. No noise.