Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add cobusgreyling/loop-engineering
/plugin install loop-engineering@loop-engineering
Open on GitHub

What 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.md has 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-engineering

This installs the whole loop-engineering plugin with all its skills

2Skills CLI (Vercel)

npx skills add cobusgreyling/loop-engineering --skill loop-budget -a claude-code

3Manually: put the files in place

~/.claude/skills/loop-budget/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/loop-budget/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set29

The whole set →
changelog-scan changelog-scan reads merges and commits made since the last release and turns them into a per-item changelog list with a summary at the end. CX Codex +1 ★ 11,819repo stars draft-release-notes draft-release-notes generates categorized release notes drafts from repository scan data into clean Markdown. Keeps prompt injection safety checks active before you publish. CX Codex +1 ★ 11,819repo stars changelog-scan changelog-scan scans recent merges, pull requests, and commits for release-note material. Use it when an agent needs structured change blocks and a scan summary. CX Codex +1 ★ 11,819repo stars draft-release-notes draft-release-notes turns a changelog scan into a sectioned draft of release notes. It proposes the text and leaves publishing to a human. CX Codex +1 ★ 11,819repo stars changelog-verifier changelog-verifier audits release note drafts against raw git commits and pull request data. Flags hallucinated bullet points, missing breaking changes, and prompt injections. CX Codex ★ 11,819repo stars loop-constraints The loop-constraints skill loads project constraints before work begins and checks them before edits, tests, pushes, and merges. CX Codex +1 ★ 11,819repo stars ci-triage ci-triage reads a failed CI run, pins the job and step that broke, and labels the cause as flake, regression, env or config before anyone writes a fix. CX Codex +1 ★ 11,819repo stars dependency-triage dependency-triage scans manifests and lockfiles for outdated or vulnerable packages. Classifies update types and prepares a prioritized patch list. CX Codex +1 ★ 11,819repo stars

Project sponsors

Companies that keep this analytics open