Skip to main content
skill CX Codex

cost-burn — Claude Code skill: what does it do, how to install

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.

MIT 248 installs ★ 82,234 updated 2026-10-25

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

What cost-burn does

This skill tracks burn-rate trends by binning session costs into configurable time windows. It calculates the delta between the latest bucket and the mean of previous non-empty buckets to highlight abnormal cost acceleration. This helps catch incidents, such as inefficient code loops, before budget alerts trigger.

To function, the skill requires existing records in the cost-tracking namespace. It skips alerts during cold starts to avoid false positives. If the acceleration percentage exceeds the --alert-on-acceleration-pct argument, the process exits with 1.

The tool is distinct from cost-trend, which focuses on benchmark drift. If the --bucket duration exceeds the --lookback period, the script will throw an error with exit code 2.

What it helps with

  • detect production spend acceleration
  • automate spend checks in CI pipelines
  • flag unexpected cost trajectory spikes
  • alert when costs exceed historical averages

Example prompts for the agent

  • Check current burn rate: cost burn --bucket 1d --lookback 7d
  • Alert if spend accelerates by 50%: cost burn --bucket 1d --lookback 14d --alert-on-acceleration-pct 50
  • Fail build on high acceleration: cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 100 || alert-oncall

How to install cost-burn

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cost-burn

How to install cost-burn in Claude Code?

Run npx skills add ruvnet/ruflo --skill cost-burn -a claude-code in your terminal.

What does cost-burn do?

It tracks production spend trajectories and provides optional exit codes for CI integration when costs accelerate beyond a defined percentage.

What is required for cost-burn?

Access to cost-tracking namespace records and Bash environment.

Source text

SKILL.md · MIT
---
name: cost-burn
description: Burn-rate trend over time with optional drift-alert exit code. Bins session spend into buckets, surfaces window-over-window delta, and can exit 1 when latest bucket exceeds prior mean by a configurable %. Distinct from `cost-trend` (benchmark drift); this tracks PRODUCTION spend trajectory.
argument-hint: "[--bucket 1d] [--lookback 14d] [--alert-on-acceleration-pct 50] [--format table|json]"
allowed-tools: Bash
disable-model-invocation: true
---

Burn-rate trend observability. The fourth leg of the cost-tracker forward-cost stack:

| Question | Skill |
|---|---|
| "Have we crossed a threshold?" (reactive) | `cost-budget-check` |
| "When will we cross a threshold?" (predictive) | `cost-projection` |
| "Could we have spent less?" (comparative) | `cost-counterfactual` |
| "Is daily burn ACCELERATING?" (trend) | **`cost-burn`** ← this |

## Algorithm

Implementation: [`scripts/burn.mjs`](../../scripts/burn.mjs).

1. Read all `session-*` records from `cost-tracking` namespace.
2. Bin into `--bucket` duration windows (default `1d`) over `--lookback` (default `14d`).
3. For each bucket: `{n: sessions, spendUsd: sum(total_cost_usd)}`.
4. Compute `delta = latest.spendUsd - mean(prior non-empty buckets)`.
5. If `--alert-on-acceleration-pct N` is set: exit 1 when `deltaPct > N`.

## Smoke transcript (5 days @ $0.10/day, today $0.50 — 400% acceleration)

```
| Latest bucket spend | $0.500000 (1 sessions) |
| Prior bucket mean | $0.100000 (4 non-empty buckets) |
| **Delta (latest vs prior mean)** | **+$0.400000 (400.00%)** |

# | Window                              | Sessions | Spend
0 | 2026-06-15 14:16 → 2026-06-16 14:16 | 1        | $0.500000
1 | 2026-06-14 14:16 → 2026-06-15 14:16 | 0        | $0.000000
2 | 2026-06-13 14:16 → 2026-06-14 14:16 | 1        | $0.100000
3 | 2026-06-12 14:16 → 2026-06-13 14:16 | 1        | $0.100000
...
```

## Drift alert exit code

  $ cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 50
  ⚠ ALERT: latest bucket $0.500000 is 400.0% above prior mean $0.100000 (threshold +50%)
  exit 1

  $ cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 500
  ✓ latest bucket within +500% of prior mean (actual delta: 400.0%) — OK
  exit 0

## CI integration

```bash
# Fail the build if today's spend accelerated > 100% over the weekly mean
cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 100 || alert-oncall
```

The alert is independent of budget — it triggers on rate ACCELERATION even
when total spend is well under budget. Catches "we shipped a hot loop that
burns 10× normal" before the budget alarm goes off.

## Distinct from `cost-trend`

| Skill | Data source | Question |
|---|---|---|
| `cost-trend` | `docs/benchmarks/runs/*.json` | "Is the benchmark drifting (win rate, latency)?" |
| `cost-burn` | `cost-tracking` namespace | "Is production spend accelerating?" |

Both useful; they answer different questions on different data.

## Edge cases

- Sparse history (no prior non-empty buckets): alert is SKIPPED with a reason string, exit 0. Operators don't get spurious alerts on cold-start.
- Prior buckets all $0 but latest > $0: delta is `Infinity`/`null` in JSON, marked `new` in the table. No alert fires (no baseline to compare against).
- `--bucket` > `--lookback`: hard error, exit 2.

© ruvnet · MIT · ruvnet/ruflo

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set155

The whole set →
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-health 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. 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-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 Ruflo The Ruflo MCP server for Claude Code and Codex coordinates agent teams and keeps memory across sessions. After init, hooks route tasks and coordinate agents in the background. CX Codex +1 ★ 82,234repo stars claude-flow Connect Claude Code to claude-flow tools for agent coordination and shared task context. The MCP setup uses ANTHROPIC_API_KEY. CX Codex +1 ★ 82,234repo stars

Project sponsors

Companies that keep this analytics open