Skip to main content
affpapa.org
RU EN
skill Claude Code CX Codex Cursor GitHub Copilot

cost-budget-check — Claude Code skill: what it does, how to install

Adds up what the project has spent, compares it with the budget limit and names the alert level. Worth running before you spawn another round of agents.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add ruvnet/ruflo --skill cost-budget-check -a claude-code
Open on GitHub

What cost-budget-check does

The skill reads the limit from cost-tracking:budget-config, sums total_cost_usd across the session-* records that cost-track writes, then returns a level: 50% INFO, 75% WARNING, 90% CRITICAL, 100% HARD_STOP. Until it shipped, the ladder was documented in the README and nothing checked it. This skill is the check.

One call does the work: node plugins/ruflo-cost-tracker/scripts/budget.mjs check. BUDGET_PERIOD=today narrows the window (default all), BUDGET_QUIET=1 swaps the markdown summary for JSON. Setting and reading the limit use the same script: budget.mjs set 50.00 and budget.mjs get. The skill is allowed Bash plus three MCP memory tools.

At 100% the script exits with code 1, so budget.mjs check && spawn … fails closed. That is the point: the guard runs before the spawn. Past 90% utilization, go to /cost-optimize before spending on more agents. /loop 30m keeps the check on a schedule.

What it helps with

  • see what a week of agent runs has cost
  • spot a budget that is running out mid-task
  • set a dollar limit and read what is left
  • block agent spawns once the budget is gone
  • keep a budget check running on a timer

Example prompts for the agent

  • run cost-budget-check for this week
  • how much budget is left? check before spawning agents
  • set the limit to 50.00 and show the current alert level

How to install cost-budget-check

1Skills CLI (Vercel)

npx skills add ruvnet/ruflo --skill cost-budget-check -a claude-code

2Manually: put the files in place

~/.claude/skills/cost-budget-check/SKILL.md

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

From the same set104

The whole set →
ruflo ruvnet This skill adds multi-agent orchestration, memory, routing, and MCP tools to a project. Use it for swarm tasks and multi-step workflows. Claude Code CX Codex Cursor +1 4,000installs Swarm Orchestration ruvnet Skill for managing agent swarms with parallel execution, dynamic topology, and automatic load balancing. Use when a single agent is not enough and you need to orchestrate specialists of different types. Claude Code CX Codex Cursor +1 2,100installs github-project-management ruvnet Turns issue triage and board upkeep into gh and ruv-swarm calls: labels, subtasks, duplicate lookup. Useful when the tracker holds more tickets than order. Claude Code CX Codex Cursor +1 1,400installs github-workflow-automation ruvnet Automates GitHub Actions with AI agent coordination. Generates optimised pipelines, manages pull requests, analyzes failed runs, and deploys updates with risk assessment. Claude Code CX Codex Cursor +1 1,300installs github-code-review ruvnet Runs a swarm of specialized AI agents to inspect GitHub pull requests for security, performance, and architecture issues. Claude Code CX Codex Cursor +1 1,300installs stream-chain ruvnet Chains sequential agent steps together using streaming JSON flow and provides ready-to-run pipelines. Claude Code CX Codex Cursor +1 1,200installs flow-nexus-swarm ruvnet Deploy cloud-based AI agent swarms and define event-driven workflows with message queues. Use it to coordinate tasks, inspect runs, and scale a swarm. Claude Code CX Codex Cursor +1 1,200installs performance-analysis ruvnet Detects bottlenecks in Claude Flow swarms, profiles agent operations, and generates reports with actionable optimization recommendations. Claude Code CX Codex Cursor +1 1,200installs

Similar

mashup-mods rehan-remade Skill for building cross-game mods: Minecraft inside Skyrim, skateboarding in MW2. Covers passthrough mods, porting content, and embedding one game into another. Claude Code CX Codex Cursor +1 1,500installs reverse-engineering rehan-remade Lets the agent read a game from the inside: decompiled code, dumped asset formats, live memory. Useful when a mod needs an exact function address or the layout of a file. Claude Code CX Codex Cursor +1 1,500installs mod-any-game rehan-remade PC game modding skill that takes an idea from engine reconnaissance and save backups to asset pipelines and in-game testing. Claude Code CX Codex Cursor +1 1,500installs skill-review sanyuan0704 Audits Claude Code skills against best practices for structure, token efficiency, and trigger quality. Delivers prioritized fixes with exact line citations. Claude Code CX Codex Cursor +1 2,200installs google-drive-automation sanjay3290 Lets an agent read and write Google Drive files through two local scripts and standalone OAuth, without an MCP server. Claude Code CX Codex Cursor +1 909installs setup-matt-pocock-skills Matt Pocock This skill configures a repository for Matt Pocock's engineering skills by setting its issue tracker, triage labels, and domain docs layout. Run it before using the other skills. Claude Code 1,052,851installs to-tickets Matt Pocock Turns a plan, spec, or conversation into small end-to-end tickets with explicit blockers. Use it to agree on the work breakdown before tickets go to a tracker. Claude Code 711,230installs writing-plans Jesse Vincent This skill turns requirements for a multi-step task into an implementation plan before code changes begin. It helps when another engineer needs exact files, interfaces, and checks. Claude Code CX Codex 282,859installs

Questions about cost-budget-check

How do I install cost-budget-check in Claude Code?

Run npx skills add ruvnet/ruflo --skill cost-budget-check -a claude-code; the skill lands at ~/.claude/skills/cost-budget-check/SKILL.md.

What does cost-budget-check do?

It reads accumulated spend from cost-track and the limit from cost-tracking:budget-config, computes utilization, then reports the alert level with a recommended action.

What happens at 100% of the budget?

You get HARD_STOP: budget.mjs check exits with code 1, so non-essential spawns should stop. Chained with &&, the spawn never runs.

Source text

SKILL.md · MIT 
---
name: cost-budget-check
description: Read accumulated cost-tracking spend + budget config, compute utilization, emit 50/75/90/100% alert ladder
argument-hint: "[--period today|week|month|all]"
allowed-tools: Bash mcp__plugin_ruflo-core_ruflo__memory_retrieve mcp__plugin_ruflo-core_ruflo__memory_list mcp__plugin_ruflo-core_ruflo__memory_store
---

# Cost Budget Check

Reads `cost-tracking:budget-config` for the project's budget limit, sums `total_cost_usd` across `session-*` records produced by `cost-track`, computes utilization, and emits the **measured** 4-tier alert ladder (50% INFO / 75% WARNING / 90% CRITICAL / 100% HARD_STOP).

Until P2 (this skill) landed, the README documented the alert ladder but no code checked it. Now this skill is the gate.

## When to use

- After every cost-track run, to surface the alert level.
- Before spawning a swarm — if utilization ≥ 90%, escalate to `/cost-optimize` first.
- Cron-friendly via `/loop 30m` for continuous monitoring.

## Steps

1. **Run the check**:

   ```bash
   node plugins/ruflo-cost-tracker/scripts/budget.mjs check
   ```

   Filter by period: `BUDGET_PERIOD=today` (default `all`). Use `BUDGET_QUIET=1` for machine-readable JSON.

2. **Inspect the markdown summary** — budget, spent, remaining, utilization percentage, alert level (🟢 OK · 🟡 INFO · 🟠 WARNING · 🔴 CRITICAL · 🛑 HARD_STOP), and the recommended action.

3. **Set / inspect the budget**:

   ```bash
   node plugins/ruflo-cost-tracker/scripts/budget.mjs set 50.00
   node plugins/ruflo-cost-tracker/scripts/budget.mjs get
   ```

4. **HARD_STOP path** — `budget.mjs check` exits with code `1` when utilization ≥ 100%. Wrap critical agent spawns in a `budget.mjs check && spawn …` guard to fail closed.

## Storage shape (`cost-tracking:budget-config`)

```json
{
  "budget_usd": 50.00,
  "setAt": "2026-05-05T...",
  "thresholds": { "info": 0.50, "warning": 0.75, "critical": 0.90, "hard_stop": 1.00 }
}
```

## Alert ladder (from REFERENCE.md, now enforced)

| Threshold | Level | Action |
|---|---|---|
| 50% | INFO 🟡 | log notification, no UX disruption |
| 75% | WARNING 🟠 | display warning, suggest `/cost-optimize` |
| 90% | CRITICAL 🔴 | urgent alert, recommend model downgrades |
| 100% | HARD_STOP 🛑 | halt non-essential spawns; exit code 1 |

## Cross-references

- `cost-track` (producer) — populates `cost-tracking:session-*`
- `cost-report` — same data source, narrative format
- `cost-optimize` — recommended action when WARNING/CRITICAL
- REFERENCE.md "Budget alert thresholds" — the documented ladder this enforces

© ruvnet · MIT · ruvnet/ruflo

See also

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor