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

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

CLAUDE DAILY COST  ·  2026-05-06 → 2026-05-08
┌─────────────┬────────┬───────────┬────────┬───────────┬──────┬────────┬──────┐
│ Date        │ Era    │      Cost │ Tokens │ Mix       │ Opus │ Sonnet │ Haiku│
├─────────────┼────────┼───────────┼────────┼───────────┼──────┼────────┼──────┤
│ 2026-05-06  │ Before │     $2.68 │   3.2M │ ████████… │ 100% │     0% │   0% │
│ 2026-05-07  │ Before │    $24.26 │  49.0M │ ████████… │  87% │     0% │  13% │
│ 2026-05-08  │ Today  │    $80.88 │ 117.9M │ ████████… │  97% │     0% │   3% │
└─────────────┴────────┴───────────┴────────┴───────────┴──────┴────────┴──────┘

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 ai-cost-compare
# or
uv tool install ai-cost-compare

3. Run:

ai-cost-compare --range 5

📦 Install

PyPI / uv

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

Homebrew

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

One-liner (no tap):

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

Requirements

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

📖 Usage

Claude Code (default)

ai-cost-compare and ai-cost-compare claude are equivalent. Legacy installs: claude-cost-compare / cccompare still work.

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

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

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

Requires ccusage on your PATH.

Cursor IDE

Option A — CSV export:

1. Go to cursor.com/dashboard/usage and export a CSV
2. Run:

ai-cost-compare cursor --file ~/Downloads/usage.csv --range 7 --cutoff 2026-05-13

Option B — session token (auto-fetch):

1. Install the API extra: pip install 'ai-cost-compare[cursor-api]'
2. Open any cursor.com page while logged in
3. Open browser DevTools → Application → Cookies → cursor.com
4. Copy the value of WorkosCursorSessionToken
5. Add it to ~/.config/ai-cost-compare/config.toml (created automatically on first run):

[cursor]
session_token = "paste-your-token-here"

6. Run:

ai-cost-compare cursor --range 5

The config file is created with instructions the first time you run ai-cost-compare cursor.

Shared flags

🧠 How it works

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

1. Provider — claude (ccusage JSON) or cursor (CSV / optional API).
2. Parse — normalizes dates, costs, and per-model buckets (provider taxonomy).
3. Analyze — splits records at --cutoff, computes averages and mix shifts.
4. Verdict — provider-specific routing health rules.
5. Render — Rich tables with era labels, mix bars, and color-coded costs.

🛠 Development

git clone https://github.com/mazulo/ai-cost-compare.git
cd ai-cost-compare
uv sync --dev
uv run pytest
uv run ai-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/ai_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.