claude-cost-compare 0.1.3

Daily Claude cost analysis with before/after comparison and model health signals

claude-cost-compare

Daily Claude spend, before/after windows, and model routing health — in your terminal.

Turn local ccusage data into three Rich tables: daily cost, split-window comparison, and per-model verdicts.

Not a ccusage fork — an interpretation layer on top. ccusage reports what you spent; this CLI adds before/after windows, mix shifts, and routing health verdicts.

Quick start · Demo · ccusage vs this tool · Install · Usage · How it works

---

✨ Why this exists

Claude Code usage can spike fast — especially when Opus routing leaks or Sonnet/Haiku tiers stop doing their job. This CLI answers three questions at a glance:

Question	Table
What did I spend each day?	Daily cost — cost, tokens, model mix
Did things change after a date?	Before vs After — avg/day, totals, mix shift
Are models routed correctly?	Real Signal — Opus / Sonnet / Haiku verdicts

No cloud upload. Reads your local ccusage JSON and prints a terminal report.

---

🔀 ccusage vs this tool

	ccusage	claude-cost-compare
Role	Usage analytics — read local logs, report spend	Interpretation layer — explain what changed and if routing looks healthy
Scope	Many agents, daily/weekly/monthly/session views	Claude Code focus: before/after split + model mix verdicts
Output	Descriptive tables & totals	Daily cost + Before vs After + Real Signal (Opus/Sonnet/Haiku)
Install both?	✅ Required (data source)	✅ Optional companion on top

Use ccusage for “what did I spend?” Use this when “did something break after I changed config on Tuesday?”

---

🖥 Demo

_{Sample fixture output · --range 7 --cutoff 2026-05-08}

Same output as plain text

claude-cost-compare --range 7 --cutoff 2026-05-08

CLAUDE DAILY COST  ·  2026-05-06 → 2026-05-26
┌─────────────┬────────┬───────────┬────────┬───────────┬──────┬────────┬──────┐
│ Date        │ Era    │      Cost │ Tokens │ Mix       │ Opus │ Sonnet │ Haiku│
├─────────────┼────────┼───────────┼────────┼───────────┼──────┼────────┼──────┤
│ 2026-05-06  │ Before │     $2.68 │   3.2M │ ████████… │ 100% │     0% │   0% │
│ 2026-05-08  │ Today  │    $80.88 │ 117.9M │ ████████… │  97% │     0% │   3% │
│ 2026-05-09  │ After  │     $9.92 │  12.1M │ ████████… │  45% │    55% │   0% │
└─────────────┴────────┴───────────┴────────┴───────────┴──────┴────────┴──────┘

BEFORE vs AFTER  ·  Split at 2026-05-08
REAL SIGNAL      ·  Post-2026-05-08 · per-model routing verdicts

---

🚀 Quick start

1. Install ccusage (peer dependency — reads your local usage data):

npm install -g ccusage

2. Install the CLI:

pip install claude-cost-compare
# or
uv tool install claude-cost-compare

3. Run:

claude-cost-compare --range 5

---

📦 Install

PyPI / uv

pip install claude-cost-compare
uv tool install claude-cost-compare
uvx claude-cost-compare --help          # run without installing

Homebrew

brew tap mazulo/claude-cost-compare https://github.com/mazulo/claude-cost-compare
brew install claude-cost-compare
npm install -g ccusage                  # still required

One-liner (no tap):

brew install https://raw.githubusercontent.com/mazulo/claude-cost-compare/main/Formula/claude-cost-compare.rb

Requirements

• Python 3.11+ (pip/uv) or Homebrew
• ccusage on your PATH (v18+; v20 period JSON field supported)

---

📖 Usage

# Last 5 days vs today (default)
claude-cost-compare --range 5

# 7-day window split at a specific date
claude-cost-compare --range 7 --cutoff 2026-05-13

# Full billing period from a start date
claude-cost-compare --since 2026-05-01 --cutoff 2026-05-13

# Daily summary only — skip comparison tables
claude-cost-compare --summary --since 2026-05-01

# Plain output (also respects NO_COLOR)
claude-cost-compare --plain --range 5

Flags

Flag	Short	Description
--range	-r	Days before cutoff for the "before" window (default: 5)
--cutoff	-c	Before/after split date YYYY-MM-DD (default: today)
--since	-s	Explicit start date — overrides --range
--summary		Daily cost table only
--plain		Disable color

---

🧠 How it works

flowchart LR
  A[ccusage JSON] --> B[Parser]
  B --> C[Window stats]
  C --> D[Before / After deltas]
  C --> E[Model verdicts]
  D --> F[Rich terminal report]
  E --> F

1. Fetch — shells out to ccusage daily for JSON (NVM-aware discovery; supports date and v20 period rows).
2. Parse — normalizes dates, costs, and per-model breakdowns.
3. Analyze — splits records at --cutoff, computes averages and mix shifts.
4. Verdict — flags Opus routing leaks, low Sonnet share, Haiku usage patterns.
5. Render — Rich tables with era labels, mix bars, and color-coded costs.

---

🛠 Development

git clone https://github.com/mazulo/claude-cost-compare.git
cd claude-cost-compare
uv sync --dev
uv run pytest
uv run claude-cost-compare --range 5

Regenerate the README demo SVG after UI changes:

uv run python scripts/export_demo.py

---

🚢 Releasing

Bump version in pyproject.toml and src/claude_cost_compare/__init__.py, push to main, then run the Publish workflow from GitHub Actions. It will:

1. Run tests and publish to PyPI
2. Update the Homebrew formula checksum
3. Create a git tag and GitHub Release
4. Refresh Homebrew Python resources on macOS

Details: docs/RELEASING.md

---

📄 License

MIT — see LICENSE.

---

Built for Claude Code power users who want spend visibility without leaving the terminal.

⭐ Star on GitHub if this saves you from an Opus routing surprise.