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
Run the check:
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.
Inspect the markdown summary — budget, spent, remaining, utilization percentage, alert level (🟢 OK · 🟡 INFO · 🟠 WARNING · 🔴 CRITICAL · 🛑 HARD_STOP), and the recommended action.
Set / inspect the budget:
node plugins/ruflo-cost-tracker/scripts/budget.mjs set 50.00
node plugins/ruflo-cost-tracker/scripts/budget.mjs get
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)
{
"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 formatcost-optimize — recommended action when WARNING/CRITICAL- REFERENCE.md "Budget alert thresholds" — the documented ladder this enforces
1---2name: cost-budget-check3description: Read accumulated cost-tracking spend + budget config, compute utilization, emit 50/75/90/100% alert ladder4---5
6# Cost Budget Check
7
8Reads `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).
9
10Until P2 (this skill) landed, the README documented the alert ladder but no code checked it. Now this skill is the gate.
11
12## When to use
13
14- After every cost-track run, to surface the alert level.
15- Before spawning a swarm — if utilization ≥ 90%, escalate to `/cost-optimize` first.
16- Cron-friendly via `/loop 30m` for continuous monitoring.
17
18## Steps
19
201. **Run the check**:
21
22 ```bash
23 node plugins/ruflo-cost-tracker/scripts/budget.mjs check
24 ```
25
26 Filter by period: `BUDGET_PERIOD=today` (default `all`). Use `BUDGET_QUIET=1` for machine-readable JSON.
27
282. **Inspect the markdown summary** — budget, spent, remaining, utilization percentage, alert level (🟢 OK · 🟡 INFO · 🟠 WARNING · 🔴 CRITICAL · 🛑 HARD_STOP), and the recommended action.
29
303. **Set / inspect the budget**:
31
32 ```bash
33 node plugins/ruflo-cost-tracker/scripts/budget.mjs set 50.00
34 node plugins/ruflo-cost-tracker/scripts/budget.mjs get
35 ```
36
374. **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.
38
39## Storage shape (`cost-tracking:budget-config`)
40
41```json
42{
43 "budget_usd": 50.00,
44 "setAt": "2026-05-05T...",
45 "thresholds": { "info": 0.50, "warning": 0.75, "critical": 0.90, "hard_stop": 1.00 }
46}
47```
48
49## Alert ladder (from REFERENCE.md, now enforced)
50
51| Threshold | Level | Action |
52|---|---|---|
53| 50% | INFO 🟡 | log notification, no UX disruption |
54| 75% | WARNING 🟠 | display warning, suggest `/cost-optimize` |
55| 90% | CRITICAL 🔴 | urgent alert, recommend model downgrades |
56| 100% | HARD_STOP 🛑 | halt non-essential spawns; exit code 1 |
57
58## Cross-references
59
60- `cost-track` (producer) — populates `cost-tracking:session-*`
61- `cost-report` — same data source, narrative format
62- `cost-optimize` — recommended action when WARNING/CRITICAL
63- REFERENCE.md "Budget alert thresholds" — the documented ladder this enforces
gabrielmoreira