# Budget Check

> >

- **Type:** Skill
- **Install:** `agentstack add skill-allemaar-open-skills-budget-check`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [allemaar](https://agentstack.voostack.com/s/allemaar)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [allemaar](https://github.com/allemaar)
- **Source:** https://github.com/allemaar/open-skills/tree/main/skills/budget-check
- **Website:** https://allemaar.com

## Install

```sh
agentstack add skill-allemaar-open-skills-budget-check
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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`](https://github.com/ryoppippi/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`:

```bash
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](https://github.com/allemaar)
- **Source:** [allemaar/open-skills](https://github.com/allemaar/open-skills)
- **License:** Apache-2.0
- **Homepage:** https://allemaar.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-allemaar-open-skills-budget-check
- Seller: https://agentstack.voostack.com/s/allemaar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.