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

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

🔀 ccusage vs this tool

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}

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

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