Skip to content
Skillsheet

loop-budget

loop-budget

Guards an autonomous loop against runaway token and time spend with daily caps, report-only mode, and kill-switches. Use when a loop runs unattended, when API costs must stay bounded, or when a cycle should degrade gracefully to reporting instead of acting.

Category
Category: loop-engineering
  • budget
  • token-limits
  • kill-switch
  • cost-control
  • guardrails

Install this skill

npx . --tool claude-code --only loop-budget

Run from a git checkout of this repo — see the README for details.

When to apply

Run at the start and end of every loop iteration whenever the loop spends tokens, money, or wall-clock time unattended. Budgets turn "run forever chasing a flaky test" into "stop, report, and let a human decide".

Configuration file (loop-budget.md)

# daily caps per pattern, in estimated tokens
triage: 50k
bugfix: 200k
refactor: 400k
# kill switches (any true → immediate exit)
loop-pause-all: false

Start of run

  1. Read loop-budget.md for caps and kill-switch flags.
  2. Read the last 24h of loop-run-log.md entries; sum tokens_estimate per pattern.
  3. Spend ≥ 80% of a pattern's cap → report-only mode: no sub-agents, no auto-fix; observations only.
  4. Spend ≥ 90% with high-priority items still open in the state file → negotiate (downscope, or ask a human to raise the cap).
  5. Spend ≥ 100%, or any kill-switch set → exit immediately with a one-line note in the state file.
  6. Nothing actionable in the watchlist → exit in under 5k tokens. Do not spawn sub-agents to "look busy".

End of run

Append one JSON line to loop-run-log.md:

{"ts":"2026-08-20T14:03:00Z","pattern":"bugfix","tokens_estimate":12300,"outcome":"fixed|partial|blocked|no-op","items":["slug-1"]}

Rules

  • Estimates are fine; honesty about estimates is mandatory. When unsure, round up.
  • Report-only mode still writes the log — data collected cheaply today budgets tomorrow correctly.
  • Never delete log lines to "reset" a budget; that's the spend problem wearing a different hat.

Related skills

  • loop-constraints — The safety rules layer that complements spending caps.
  • loop-triage — Decides what's worth spending the budget on.