Skip to main content
skill CX Codex

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

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

What 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 1 and report which subcheck failed.
  • Do a fast smoke pass with cost health --skip burn.
  • Add a cost health --alert-days-to-exhaust 30 step 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-code

2Manually: put the files in place

~/.claude/skills/cost-health/SKILL.md

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

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

Similar skills

All skills for DevOps and infrastructure →

From the same set155

The whole set →
gaia-architecture-comparison gaia-architecture-comparison — a skill for Claude Code, Codex, Cursor, Copilot, and Gemini CLI that runs a side-by-side breakdown of the ruflo GAIA harness against Princeton's HAL reference across nine dimensions. CX Codex +1 433installs nested-subagents nested-subagents spawns a tree of sub-agents where each child can spawn its own children. Useful when intermediate state would overflow a single agent's context. CX Codex +1 317installs cost-session cost-session is a Claude Code skill that breaks down costs per message in a session to reveal expensive requests. CX Codex +1 249installs cost-projection The cost-projection Claude Code skill projects future spend from recent session data. It estimates daily costs and shows when configured budget thresholds may be reached. CX Codex +1 249installs cost-counterfactual cost-counterfactual evaluates LLM routing by comparing actual session spend against hypothetical always-haiku, always-sonnet, and always-opus baselines. Useful for tracking over-escalation and ROI. CX Codex +1 249installs cost-diff The cost-diff Claude Code skill compares two JSON snapshots of spending. Use it to detect cost changes between a baseline and a pull request branch. CX Codex +1 248installs cost-burn cost-burn — a skill for Claude Code and other platforms that observes production spend trends. It triggers in CI to detect if daily spend acceleration exceeds a specified threshold. CX Codex +1 248installs cost-anomaly The cost-anomaly Claude Code skill detects individual sessions with unusual spend and reports their modified z-scores. It runs when a request is about pinpointing a costly outlier session rather than tracking an aggregate trend. CX Codex +1 248installs

Project sponsors

Companies that keep this analytics open