Budget Check

/budget-check

A pre-wave usage gate. Launching a multi-agent wave is the most expensive thing an agent does — N concurrent subagents, each burning tokens. /budget-check answers one question before you spend: is the current usage window close enough to its ceiling that starting a wave is reckless? It returns go, no-go, or unknown, and it fails closed — with no usage data it returns unknown, never a convenient "go".

It is deliberately small: a concrete wrapper around the public ccusage reader, not a judgment engine. It does not add a global rule or amend your operating directives — it is a skill you call, so the gate lives at the decision point, not as standing policy.

> Structured execution spec: [protocol.yon](protocol.yon). Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

The check — one tool, three verdicts

The skill ships [references/tools/budget-check.mjs](references/tools/budget-check.mjs) inside its own folder. Resolve the installed skill directory and run the bundled tool, which wraps ccusage blocks --json:

node /references/tools/budget-check.mjs                  # go/no-go vs 95% of your historical-peak block
node /references/tools/budget-check.mjs --threshold 90   # custom threshold (percent)
node /references/tools/budget-check.mjs --token-limit 200000000   # explicit ceiling instead of the auto peak
node /references/tools/budget-check.mjs --json           # machine-readable verdict

• Ceiling = --token-limit if you pass one, else the largest historical (non-active) block's total tokens — ccusage's own max notion, i.e. "your usual peak window." Without --token-limit, the gate measures against your own historical peak — a relative signal ("am I near my personal worst window"), not your real plan budget. For a true budget gate, pass --token-limit with your plan's actual token ceiling.
• Verdict = go when the active block is under the threshold, no-go at or over it, unknown when there is no usage data, no active block, or no ceiling to measure against.
• Exit code = 0 go · 1 no-go · 2 unknown — so a dispatch script can gate on it directly.
• On no-go it also reports secondsUntilWindowClears and a min(3600, …) poll interval, so you know how long until the window resets.

How to use it

1. Before a wave (a fan-out of subagents, a prime-sweep, an orchestrated run), call /budget-check.
2. GO → launch the wave.
3. NO-GO → trim the wave (fewer concurrent workers), wait for the window to clear (the reported interval), or proceed deliberately — your call, surfaced not forced.
4. UNKNOWN → the gate cannot vouch; decide on other grounds and say so. A common, fixable cause is no inferable ceiling (a fresh environment with no historical block) — pass --token-limit with your plan's real token budget to get a meaningful gate.

This is a runtime tool — it reads your local usage logs, so it has nothing to measure in CI. The value is at the live pre-wave decision point, never in a pipeline.

Boundary

• Not /ask-gate — that triages a handler-facing question; budget-check gates a spend.
• Not /orchestrate-mode or /multi-agent-mode — those run the wave; budget-check only decides whether it should start.
• It encodes no policy and amends no directive: a skill you call, not a rule that fires.

> Human output. This skill's handler-facing output obeys the human-output > contract (human-output/SKILL.md).

> Next skills. On completion, run the Next Skills protocol: surface the front-matter recommendations for the caller to pick. Offer only — never auto-invoke.

> Self-improvement. On completion, run the Self-Improvement Protocol: if this run surfaced a concrete, blocking-or-recurring weakness in this skill, propose a specific fix for the handler to approve. Conservative — silent otherwise. Never auto-apply.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: allemaar
• Source: allemaar/open-skills
• License: Apache-2.0
• Homepage: https://allemaar.com

Install and usage instructions live in the source repository linked above.