loop-budget — Claude Code skill: what it does, install
loop-budget is a skill that checks token budgets and run spend before and after each iteration, stopping when the budget is exhausted or no actionable items remain.
MIT ★ 11,819 updated 2026-10-29
/plugin marketplace add cobusgreyling/loop-engineering
/plugin install loop-engineering@loop-engineeringWhat loop-budget does
This skill runs at both ends of every loop iteration. Before work starts, it reads loop-budget.md, reviews the last 24 hours in loop-run-log.md, and totals tokens_estimate for the active pattern. At 80% of the daily cap, it switches to report-only mode, with no sub-agent spawns or auto-fixes. At 100%, or when loop-pause-all is set, the iteration exits immediately.
At 90%, remaining High Priority items in STATE.md can be passed to budget-negotiator when that skill is installed. An empty watchlist or state also triggers an exit in under 5k tokens. After the run, the skill appends a JSON record to loop-run-log.md with duration, item counts, actions, escalations, estimated tokens, and outcome. The guard depends on loop-budget.md, STATE.md, and loop-run-log.md.
What it helps with
- check token spend before a loop run
- stop iterations at the daily cap
- avoid spawning sub-agents with no actionable work
- switch a run to report-only mode
- record loop usage and outcome
Example prompts for the agent
- Check the budget and recent log before starting the next loop iteration.
- Run the loop, but exit when
STATE.mdhas no actionable items. - After the iteration, append its token estimate and outcome to
loop-run-log.md.
How to install loop-budget
1Plugin marketplace
/plugin marketplace add cobusgreyling/loop-engineering/plugin install loop-engineering@loop-engineeringThis installs the whole loop-engineering plugin with all its skills
2Skills CLI (Vercel)
npx skills add cobusgreyling/loop-engineering --skill loop-budget -a claude-code3Manually: put the files in place
~/.claude/skills/loop-budget/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/loop-budget/
1Skills CLI (Vercel)
npx skills add cobusgreyling/loop-engineering --skill loop-budget -a codex2Manually: put the files in place
.agents/skills/loop-budget/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add cobusgreyling/loop-engineering --skill loop-budget -a cursor2Manually: put the files in place
.cursor/skills/loop-budget/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install cobusgreyling/loop-engineering skills/loop-budget2Manually: put the files in place
.github/skills/loop-budget/SKILL.md1Skills CLI (Vercel)
npx skills add cobusgreyling/loop-engineering --skill loop-budget -a gemini-cli2Platform CLI
gemini skills install https://github.com/cobusgreyling/loop-engineering --path skills/loop-budgetManually: put the files in place
.devin/skills/loop-budget/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about loop-budget
How do I install loop-budget in Claude Code?
Run /plugin marketplace add cobusgreyling/loop-engineering, then run /plugin install loop-engineering@loop-engineering.
What does loop-budget do?
It checks token usage around each loop iteration, limits work as the daily cap is approached, and records the result in loop-run-log.md.
When does loop-budget stop a loop?
It exits at 100% spend, when loop-pause-all is set, or when no actionable items remain. At 80% spend, it enters report-only mode and skips sub-agents and auto-fixes.
Source text
SKILL.md · MIT
---
name: loop-budget
description: Check token budget and run-log spend before and after a loop run. Enforces early exit when over budget or when there is no actionable work.
---
# 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](../budget-negotiator/SKILL.md) 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`:
```json
{
"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**.
© Cobus Greyling · MIT · cobusgreyling/loop-engineering