Skip to main content
skill CX Codex

cost-diff — Claude Code skill for cost comparisons

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.

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-diff -a claude-code
Open on GitHub

What cost-diff does

cost-diff compares spending and session counts in two JSON snapshots produced by cost summary --format json. It reports changes by model and tier, labels entries as added, removed, or changed, and sorts the table by the size of each delta.

Threshold flags make the command exit with code 1 when total spending crosses a percentage or dollar limit, or when a token class exceeds its limit. The snapshot files need total_cost_usd and sessionCount; invalid JSON or an incompatible structure returns code 2. A PR check can compare a baseline captured on the main branch with a snapshot from the PR branch.

What it helps with

  • compare spending in baseline and current snapshots
  • find models with the largest cost changes
  • fail a PR check when spending crosses a threshold
  • track spending growth by token class

Example prompts for the agent

  • Compare baseline.json with current.json and show the changes.
  • Check baseline.json against current.json and fail if total spending rises by more than 10%.
  • Compare the snapshots and alert if cache_write grows by more than 50%.

How to install cost-diff

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

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

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

Questions about cost-diff

How do I install cost-diff in Claude Code?

Run npx skills add ruvnet/ruflo --skill cost-diff -a claude-code. The skill file is at ~/.claude/skills/cost-diff/SKILL.md.

What does cost-diff do?

It compares two JSON spending snapshots, reports changes by model and tier, and checks configured thresholds. For a PR, compare its snapshot with a baseline.

What does cost-diff need to run?

It needs two JSON files created with cost summary --format json. Each snapshot must contain total_cost_usd and sessionCount.

Source text

SKILL.md · MIT
---
name: cost-diff
description: Snapshot delta between two cost-summary JSON outputs. PR-level cost regression detection — answers "what changed between these two specific snapshots?". Pairs with cost-summary's stable JSON contract.
argument-hint: "--baseline <baseline.json> --current <current.json> [--alert-on-pct N] [--alert-on-usd N] [--alert-on-class-pct <class>:N[,<class>:N]] [--format table|json]"
allowed-tools: Bash
disable-model-invocation: true
---

PR-level cost regression detection. Where cost-counterfactual compares
to HYPOTHETICAL baselines (always-haiku/sonnet/opus) and cost-burn
compares latest bucket to PRIOR MEAN, cost-diff compares two SPECIFIC
known-good snapshots.

| Question | Skill |
|---|---|
| "What would we have spent at always-X?" | `cost-counterfactual` |
| "Is daily burn accelerating vs prior mean?" | `cost-burn` |
| "Did THIS PR add spend vs main?" | **`cost-diff`** ← this |

## Algorithm

Implementation: [`scripts/diff.mjs`](../../scripts/diff.mjs). Consumes the
stable JSON contract from `cost summary --format json`.

1. Load `--baseline` and `--current` JSON snapshots.
2. Sanity check: both must have `total_cost_usd` + `sessionCount` (cost-summary shape).
3. Per-key delta: `byTier` (haiku/sonnet/opus) and `byModel` (each model).
4. Each entry tagged `added` / `removed` / `changed` based on
   baseline / current zero-ness.
5. Sort table by `|delta|` descending so the biggest movers are at the top.
6. `--alert-on-pct N`: exit 1 when `total_pct > N`.
7. `--alert-on-usd N`: exit 1 when `total_delta_usd > N`.
   Both can be set; first to trigger wins.

## PR-gate workflow

```bash
# Capture baseline (e.g. on main, via the cost-tracker-smoke CI workflow)
cost summary --format json > baseline.json

# On the PR branch, capture current state
cost summary --format json > current.json

# Compare; fail the PR if total spend grew >10% OR >$5
cost diff --baseline baseline.json --current current.json \
          --alert-on-pct 10 --alert-on-usd 5.00
```

The combination of both flags catches:
- **Percent-only fires**: a small absolute change but a meaningful shift
  (e.g. doubling from $0.10 to $0.20 hits +100% but only +$0.10).
- **USD-only fires**: a large absolute change with a small percent
  (e.g. growing from $100 to $110 is only +10% but +$10).

Either signal can fail the PR independently — they're OR'd.

## --alert-on-class-pct (iter 86)

The two USD-level thresholds above miss a regression class: when ONE
token type grows disproportionately even though total spend grows
modestly. Example: a PR introduces a verbose context-cache pattern,
total spend grows only 10% (under --alert-on-pct 50), but `cache_write`
tokens grow 900%. The iter-82 driver hides inside the USD signal.

`--alert-on-class-pct cache_write:50` exits 1 when cache_write tokens
grow more than 50% baseline → current. Multiple classes can be checked
in one flag (comma-separated):

```bash
cost diff --baseline baseline.json --current current.json \
          --alert-on-class-pct cache_write:50,output:25
```

First class to breach wins. Valid classes: `input | output | cache_write | cache_read`.

Recommended PR-gate triad:

```bash
cost diff --baseline ... --current ... \
          --alert-on-pct 25 \
          --alert-on-usd 5.00 \
          --alert-on-class-pct cache_write:100
```

Three orthogonal signals — `pct` (total grew), `usd` (large absolute
jump), `class-pct` (composition shifted). Each catches what the others
miss; AND-of-OR semantics means any one firing fails the PR.

## Smoke transcript (synthetic baseline + current)

```
| Total spend       | $1.000000 | $1.500000 | +$0.500000 | 50.00% |
| Sessions          | 10        | 13        | +3         | 30.00% |

## By tier
| opus   | $0      | $0.60   | +$0.600000 | new      | added   |
| sonnet | $0.70   | $0.50   | -$0.200000 | -28.57%  | changed |
| haiku  | $0.30   | $0.40   | +$0.100000 | 33.33%   | changed |
```

Notice the table is **sorted by absolute delta**, not alphabetically —
the biggest mover (opus newly added) bubbles to the top. Operators
reading top-down see "what mattered" first.

## Exit codes

| Exit | Meaning |
|---|---|
| 0 | No alert, OR no thresholds set |
| 1 | --alert-on-pct or --alert-on-usd threshold exceeded |
| 2 | Config error (missing files, invalid JSON, malformed snapshot) |

## Status column

| Status | Meaning |
|---|---|
| `added` | This tier/model was $0 in baseline, >$0 in current |
| `removed` | This tier/model was >$0 in baseline, $0 in current |
| `changed` | Both baseline and current >$0; delta is the difference |

Entries with `baseline === 0 && current === 0` are dropped (nothing to
report).

## Composition with cost-summary

cost-diff is the SECOND HALF of a contract that cost-summary started:
the stable JSON shape from `cost summary --format json`. Both pieces
have been frozen — adding fields to summary is fine; renaming or
removing isn't.

If you're consuming snapshots elsewhere (dashboards, alerting), the
same shape works — `cost-diff` is just one consumer.

© ruvnet · MIT · ruvnet/ruflo

Similar skills

All skills for DevOps and infrastructure →

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-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 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