mcpField
L
loop-budget

loop-budget

github.com/cobusgreylingAgent workflows11.7k167 installsUpdated today
Repository

About loop-budget

loop-budget is an agent skill for checking an automated loop's token spend, daily caps, and pause flags at the start and end of each run. It throttles or exits when limits are reached and records run statistics.

Key features

  1. 01Daily cap and pause-flag checks
  2. 02Token usage tracking by pattern
  3. 03Report-only mode at budget threshold
  4. 04Early exit when no work is actionable
  5. 05Run-log and alert updates

Use cases

  1. 01Limiting token use in recurring automation
  2. 02Stopping a loop when its budget is exhausted
  3. 03Avoiding agent spawns when nothing needs action

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/cobusgreyling/loop-engineering --skill loop-budget

After installing, type/loop-budgetin Claude Code to confirm it loaded.

Details

From the project README

Loop Budget Guard

Run at the start and end of every loop iteration.

Start of run

  1. Read loop-budget.md for daily caps and kill-switch flags.
  2. Read recent entries in loop-run-log.md (last 24h).
  3. Sum tokens_estimate for the active pattern today.
  4. If spend ≥ 80% of the pattern's daily cap → report-only mode (no sub-agents, no auto-fix).
  5. If spend ≥ 90% and High Priority items remain in STATE.md, yield to the budget-negotiator skill (if installed). Otherwise, if spend ≥ 100% or loop-pause-all is set → exit immediately with a one-line note in STATE.md.
  6. If watchlist/state has no actionable items → exit in <5k tokens (do not spawn sub-agents).

End of run

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

{
  "run_id": "<ISO8601>",
  "pattern": "<pattern-id>",
  "duration_s": <number>,
  "items_found": <number>,
  "actions_taken": <number>,
  "escalations": <number>,
  "tokens_estimate": <number>,
  "outcome": "no-op | report-only | fix-proposed | escalated"
}

Rules

  • Never exceed max sub-agent spawns/run from loop-budget.md.
  • High-cadence patterns (CI Sweeper, PR Babysitter) must early-exit when nothing is actionable.
  • On self-throttle, append a line to loop-budget.md under Alerts This Period.

Comments

Markdown supported