A command-line tool for analyzing Claude Code usage data. Displays terminal-formatted tables with usage metrics, costs, and model breakdowns.
╭───────────────────────────── Summary Statistics ─────────────────────────────╮
│ Total requests: 1,886 │
│ Total tokens: 172.56M │
│ Average tokens per request: 91.5K │
│ Average cost per request: $0.20 │
│ Input/Output ratio: 0.10:1 │
│ Total cost: $380.11 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── ROI Analysis ────────────────────────────────╮
│ Subscription Analysis │
│ │
│ Monthly Subscription: $200.00 (unlimited) │
│ Period (7 days): $46.67 │
│ │
│ Pay-as-you-go cost would be: $380.11 │
│ You're saving: $333.44 │
│ Discount: 87.7% off regular pricing │
│ │
│ Getting 8.1x value from your subscription │
│ │
│ Status: ✓ SUBSCRIPTION WORTH IT │
│ You're saving $333.44 vs pay-as-you-go API pricing! │
│ │
│ Break-even point: $6.67/day usage │
╰──────────────────────────────────────────────────────────────────────────────╯
Usage by Model
╭──────────┬──────────┬──────────┬──────────┬───────────┬──────────┬───────────╮
│ Model │ Requests │ Input │ Output │ Cache │ Cache │ Total │
│ │ │ Tokens │ Tokens │ Create │ Read │ Cost │
├──────────┼──────────┼──────────┼──────────┼───────────┼──────────┼───────────┤
│ Opus 4 │ 1,470 │ 3.0K │ 163.9K │ 8.37M │ 126.68M │ $359.38 │
│ Sonnet 4 │ 416 │ 17.6K │ 48.1K │ 2.54M │ 34.73M │ $20.73 │
├──────────┼──────────┼──────────┼──────────┼───────────┼──────────┼───────────┤
│ TOTAL │ 1,886 │ 20.6K │ 211.9K │ 10.92M │ 161.40M │ $380.11 │
╰──────────┴──────────┴──────────┴──────────┴───────────┴──────────┴───────────╯
Recent Daily Usage
╭─────────────┬──────────┬─────────┬─────────┬───────╮
│ Date │ Requests │ Tokens │ Cost │ Trend │
├─────────────┼──────────┼─────────┼─────────┼───────┤
│ Mon, Aug 18 │ 366 │ 32.69M │ $26.65 │ ↑ │
│ Sun, Aug 17 │ 64 │ 3.78M │ $5.13 │ ↓ │
│ Fri, Aug 15 │ 474 │ 45.58M │ $98.54 │ ↑ │
│ Thu, Aug 14 │ 200 │ 18.30M │ $51.39 │ ↓ │
│ Wed, Aug 13 │ 534 │ 48.22M │ $131.15 │ ↑ │
│ Tue, Aug 12 │ 201 │ 22.09M │ $54.58 │ ↑ │
│ Mon, Aug 11 │ 32 │ 1.30M │ $11.14 │ │
├─────────────┼──────────┼─────────┼─────────┼───────┤
│ Last 7 Days │ 1,871 │ 171.96M │ $378.59 │ │
╰─────────────┴──────────┴─────────┴─────────┴───────╯
- Usage Analytics - View requests, tokens, and costs by model
- Project Analytics - Breakdown usage by project with
--by-project - Performance Caching - Fast data loading with intelligent caching
- Flexible Date Filtering - Support for hours, days, weeks, months (1h, 7d, 2w, 3m, today, yesterday, etc.)
- Model Filtering - Focus on specific Claude models
- Cost Breakdown - Detailed cost analysis with cache token pricing
- Daily Trends - View usage trends with weekly summaries and indicators
- Terminal Output - Beautiful colored tables using Rich
- Debug Mode - Troubleshoot with
--debugflag
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
# Install package in development mode
pip install -e .The claude-usage command will now be available in your activated virtual environment.
# Show all usage data
claude-usage
# Show last 7 days
claude-usage --range 7d
# Show last 30 days with project breakdown
claude-usage --range 30d --by-project
# Calculate ROI vs $200/month subscription
claude-usage --roi 200
# Show ROI for last 30 days
claude-usage --range 30d --roi 200
# Show today's usage
claude-usage --range today
# Show last 2 weeks
claude-usage --range 2w
# Filter by model
claude-usage --model opus
# Force refresh (ignore cache)
claude-usage --no-cache
# Debug mode
claude-usage --debug
# Show help
claude-usage --help-h, --help- Show help message-r, --range <range>- Filter by date range (e.g., 1h, 7d, 2w, 3m, today, yesterday, all)-m, --model <model>- Filter by specific model-p, --by-project- Show breakdown by project--roi <amount>- Calculate ROI vs monthly subscription cost (e.g., --roi 200 for $200/month)--no-cache- Force refresh data (ignore cache)--debug- Show debug information
Reads Claude Code usage data from ~/.claude/projects/*/**.jsonl files.
- Claude Opus 4 (
claude-opus-4) - Claude Opus 4.1 (
claude-opus-4-1) - Claude Sonnet 4 (
claude-sonnet-4) - Claude 3.5 Sonnet (
claude-3.5-sonnet) - Claude Haiku (when available)
Pricing calculated using current Anthropic rates including cache token costs.
- 💰 ROI Analysis - Calculate savings vs monthly subscription with
--roi - 📊 Break-even Calculator - See your daily break-even usage target
- 📊 Project Analytics - See which projects use the most tokens
- ⚡ Performance Caching - 10x faster loading with smart cache
- 🔧 Model Consolidation - No more duplicate Opus 4 entries
- 📈 Daily Trends - Trend indicators and weekly summaries
- 🐛 Better Error Messages - Helpful guidance when things go wrong
- 🎯 More Date Formats - Support for hours, weeks, months, special keywords