cost-health — Claude Code skill: composite cost CI gate
cost-health runs four cost checks at once and returns a single status: budget, burn acceleration, session outliers and days left before the budget is gone.
MIT 249 installs ★ 82,234 updated 2026-11-01
npx skills add ruvnet/ruflo --skill cost-health -a claude-codeWhat cost-health does
One command, cost health, wraps four cost checks. Each answers its own question: is the budget blown, is daily spend climbing, does a single session stand out, how long until the budget runs out. scripts/health.mjs spawns all four at the same time, reads their JSON output, then prints a line per check and a HEALTHY or UNHEALTHY badge.
The gate exits with the highest code among the subchecks. A config error (2) outranks an alert (1), so a broken pipeline surfaces instead of passing as healthy. Projection has no exit code of its own; one is derived from --alert-days-to-exhaust.
Thresholds arrive as flags — --alert-acceleration, --alert-outliers, --alert-days-to-exhaust. --skip burn,projection drops the slow ones. With no budget configured, projection is skipped rather than failed, and the summary says so.
What it helps with
- gate CI on four cost checks in one step
- catch a runaway session by z-score
- see how many days of budget remain
- drop the slow checks on a smoke run
- tell a misconfigured gate from a real alert
Example prompts for the agent
- Run
cost health --alert-acceleration 100 --alert-outliers 1and report which subcheck failed. - Do a fast smoke pass with
cost health --skip burn. - Add a
cost health --alert-days-to-exhaust 30step to the CI workflow for a quarterly review.
How to install cost-health
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-health -a claude-code2Manually: put the files in place
~/.claude/skills/cost-health/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cost-health/
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-health -a codex2Manually: put the files in place
.agents/skills/cost-health/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-health -a cursor2Manually: put the files in place
.cursor/skills/cost-health/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ruvnet/ruflo plugins/ruflo-cost-tracker/skills/cost-health2Manually: put the files in place
.github/skills/cost-health/SKILL.md1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-health -a gemini-cli2Platform CLI
gemini skills install https://github.com/ruvnet/ruflo --path plugins/ruflo-cost-tracker/skills/cost-healthManually: put the files in place
.devin/skills/cost-health/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill cost-health -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about cost-health
How do I install cost-health in Claude Code?
Run npx skills add ruvnet/ruflo --skill cost-health -a claude-code. The skill file lands at ~/.claude/skills/cost-health/SKILL.md.
What does cost-health do?
It runs the budget, burn, anomaly and projection checks in parallel and reports one status using the strictest exit code.
What do the exit codes mean?
0 means every subcheck passed, 1 means at least one alert fired, 2 means a config or argument error, 127 means a subcheck failed to launch.
Source text
SKILL.md · MIT
--- name: cost-health description: Composite CI gate — runs cost-budget-check + cost-burn + cost-anomaly + cost-projection in parallel and surfaces a single combined health status with max exit code. The operationally-useful entry point — one shell-out covers all four alert ladders. argument-hint: "[--alert-acceleration 100] [--alert-outliers 1] [--alert-days-to-exhaust 14] [--skip burn,anomaly] [--format table|json]" allowed-tools: Bash disable-model-invocation: true --- The four CI-gate skills (budget / burn / anomaly / projection) each answer a different question. This skill composes them — runs all four IN PARALLEL, returns `max(exit_codes)`, prints a one-line summary per check. | Subcheck | Question | Default threshold | |---|---|---| | `budget` | "Have we crossed the configured budget?" | HARD_STOP at 100% | | `burn` | "Is daily burn accelerating?" | +100% vs prior-week mean | | `anomaly` | "Is any specific session a >3.5σ outlier?" | ≥1 outlier | | `projection` | "When will we hit 100% of budget?" | <14 days | ## Algorithm Implementation: [`scripts/health.mjs`](../../scripts/health.mjs). 1. Spawn all four subcheck scripts in parallel (`Promise.all` over `child_process.spawn`). 2. Each subcheck emits `--format json`; parse and capture exit code. 3. Projection has no built-in exit code — synthesize one from `daysUntilReached[100%] < --alert-days-to-exhaust`. 4. Final exit code = `max(subcheck exits)`. Any single failure fails the gate. 5. Print one-line summary per check + overall HEALTHY/UNHEALTHY badge. ## CI integration ```yaml - name: Cost health gate run: cost health --alert-acceleration 100 --alert-outliers 1 ``` A single step covers four alert ladders. Before this skill you'd wire four separate gates that each duplicated the npx + memory-list overhead; now it's one shell-out (and the four subcheck npx calls run in parallel internally). ## Customizing thresholds ```bash # Quarterly review — stricter thresholds cost health --alert-acceleration 50 --alert-outliers 1 --alert-days-to-exhaust 30 # Production drift gate — only fire on egregious changes cost health --alert-acceleration 200 --alert-outliers 3 --alert-days-to-exhaust 7 # Skip the slow burn check during a smoke run cost health --skip burn ``` ## Smoke transcript (5 healthy sessions, then add 1 outlier) ``` # Healthy Overall: ✓ HEALTHY (max exit code 0) | Check | Status | Detail | | budget | ✓ | unknown — no budget configured | | burn | ✓ | delta within ±100% | | anomaly | ✓ | 0 outliers — under threshold ≥1 | | projection | ✓ | no budget configured — skipping | # After adding $5 outlier (vs $0.10 baseline) Overall: ⚠ UNHEALTHY (max exit code 1) | burn | ⚠ | ALERT 5163.2% acceleration: latest bucket $5.00 is 5163.2% above prior mean $0.095 | | anomaly | ⚠ | ALERT 1 outlier (|z|>3.5) | ``` ## Skipping subchecks ```bash cost health --skip burn,projection # only budget + anomaly ``` Useful when: - A subcheck doesn't apply (no budget set → skip projection) - A subcheck is too slow for fast-feedback contexts (smoke runs) - A subcheck is being independently CI-gated already ## Exit code semantics | Exit | Meaning | |---|---| | 0 | All subchecks OK | | 1 | At least one subcheck fired an alert (budget HARD_STOP, burn drift, anomaly outlier, projection imminent-exhaust) | | 2 | A subcheck had a config/usage error (e.g. invalid CLI args propagated to a subscript) | | 127 | A subcheck failed to launch (script missing, etc.) | `max()` means the worst signal wins — exit 2 (config error) always dominates exit 1 (alert), so you spot misconfigured pipelines before they masquerade as healthy.
© ruvnet · MIT · ruvnet/ruflo