skills.rest
allemaar
allemaarCOMMUNITY
Explore all skills by this author →
Website𝕏@allemaarGitHub

budget-check

Checks active Claude Code usage against a token ceiling before launching multi-agent waves.

14|1|Updated Jun 14, 2026
Search Tags:#claude code#multi-agent#pre-flight check#token budget#rate limit#ccusage#usage gate
One-click install
npx skills add https://github.com/allemaar/open-skills --skill budget-check-allemaar
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: budget-check
Source: https://github.com/allemaar/open-skills/tree/main/skills/budget-check
Command: npx skills add https://github.com/allemaar/open-skills --skill budget-check-allemaar

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires ccusage, and includes references (resource) components.

What problem does it solve? Launching a multi-agent wave is the most expensive action an AI agent takes, and starting one near your usage ceiling can burn through your window mid-run. This Skill gates that decision by checking your current usage block against a threshold before any fan-out begins. ## Core Features & Use Cases - Go / No-Go / Unknown Verdicts: Wraps ccusage blocks --json to compare the active usage block against a threshold (default 95%) and returns a clear verdict with exit codes 0, 1, or 2. - Fail-Closed Design: Returns unknown — never a fabricated go — when usage data, an active block, or a ceiling is unavailable. - Flexible Ceilings: Measures against your historical peak block by default, or against a real plan budget via --token-limit <N>. - Use Case: Before dispatching an orchestrated run of five parallel subagents, run the gate; on NO-GO it reports how many seconds until the window clears so you can trim the wave or wait. ## Quick Start Ask the agent to run /budget-check before launching the planned multi-agent wave and only proceed on a go verdict.

Frequently Asked Questions about budget-check

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check Claude Code token usage before running subagents?▼

Run the bundled budget-check.mjs script with node, which wraps ccusage blocks --json and compares the active usage block against a 95% threshold. It prints a go or no-go verdict and exits with code 0 or 1 so dispatch scripts can gate on it directly.

How do I set a custom token limit for the usage gate?▼

Pass --token-limit <N> with your plan's actual token ceiling, for example node budget-check.mjs --token-limit 200000000. Without it, the gate measures against your historical peak block, which is a relative signal rather than a real budget.

What does ccusage measure in Claude Code?▼

ccusage reads Claude Code's local usage logs and reports token consumption grouped into 5-hour blocks, including the currently active block and historical peaks. The budget-check tool uses the active block's totalTokens against a ceiling to produce its verdict.

Why does budget-check return unknown instead of go?▼

It returns unknown when ccusage is unavailable, there is no active usage block, or no ceiling can be determined. This fail-closed design prevents a false go when the gate has no data to vouch for the decision.

Can budget-check run in CI pipelines?▼

No, it is a runtime tool that reads your local Claude Code usage logs, which do not exist in CI environments. Its value is at the live pre-wave decision point, not in automated pipelines.

Related Skills

Explore More Software Engineering Skills→
ByronWilliamsCPAByronWilliamsCPA

usage-report

Summarizes Claude Code token usage and cost from local JSONL transcripts via ccusage.

Official
Intermediate
mykaarmamykaarma
4

launch-team

Dispatch five parallel agents to assess security, localization, performance, observability, and launch checklist.

Official
Advanced
kmshihab7878kmshihab7878
6

cost-optimization

Analyze cloud and AI consumption costs across Terraform, AWS, and Claude Code usage.

Community
Intermediate
Nandansai08Nandansai08
1

runaway-cost-guardrails

Enforces iteration, token, time, and action caps on agent loops to stop runaway spend.

Community
Advanced