ccusage(claude-code-usage)

A CLI tool for analyzing Claude Code usage from local JSONL files.

Inspired by this article about tracking Claude Code usage costs.

Claude Code's Max plan offers unlimited usage - but wouldn't it be interesting to know how much you'd be paying if you were on a pay-per-use plan?

This tool helps you understand the value you're getting from your subscription by calculating the equivalent costs of your actual usage. See how much you're saving and enjoy that satisfying feeling of getting great value! 😊

• 📊 Daily Report: View token usage and costs aggregated by date
• 💬 Session Report: View usage grouped by conversation sessions
• 📅 Date Filtering: Filter reports by date range using --since and --until
• 📁 Custom Path: Support for custom Claude data directory locations
• 🎨 Beautiful Output: Colorful table-formatted display
• 📄 JSON Output: Export data in structured JSON format with --json
• 💰 Cost Tracking: Shows costs in USD for each day/session
• 🔄 Cache Token Support: Tracks and displays cache creation and cache read tokens separately

• This tool only reads local JSONL files generated by Claude Code. If you use Claude Code with multiple devices, you need to ensure the JSONL files are synchronized across devices.
• API usage for tools like Web Search, Code Execution, and Image Analysis are not included in the token usage reports. The tool only tracks language model token usage.

Run directly without installation:

# Using npx
npx ccusage@latest

# Using bunx
bunx ccusage

# Install globally with npm
npm install -g ccusage

# Install globally with bun
bun install -g ccusage

# Then run
ccusage daily

# Clone the repository
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# Install dependencies
bun install

# Run the tool
bun run report [subcommand] [options]

Shows token usage and costs aggregated by date:

# Show all daily usage
ccusage daily
# or: ccusage
# or: npx ccusage@latest daily
# or: bunx ccusage daily

# Filter by date range
ccusage daily --since 20250525 --until 20250530

# Use custom Claude data directory
ccusage daily --path /custom/path/to/.claude

# Output in JSON format
ccusage daily --json

ccusage is an alias for ccusage daily, so you can run it without specifying the subcommand.

Shows usage grouped by conversation sessions, sorted by cost:

# Show all sessions
ccusage session

# Filter sessions by last activity date
ccusage session --since 20250525

# Combine filters
ccusage session --since 20250525 --until 20250530 --path /custom/path

# Output in JSON format
ccusage session --json

All commands support the following options:

• -s, --since <date>: Filter from date (YYYYMMDD format)
• -u, --until <date>: Filter until date (YYYYMMDD format)
• -p, --path <path>: Custom path to Claude data directory (default: ~/.claude)
• -j, --json: Output results in JSON format instead of table
• -h, --help: Display help message
• -v, --version: Display version

╭──────────────────────────────────────────╮
│                                          │
│  Claude Code Token Usage Report - Daily  │
│                                          │
╰──────────────────────────────────────────╯

┌──────────────┬────────┬─────────┬──────────────┬────────────┬──────────────┬────────────┐
│ Date         │ Input  │ Output  │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├──────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┤
│ 2025-05-30   │    277 │  31,456 │          512 │      1,024 │       33,269 │     $17.58 │
│ 2025-05-29   │    959 │  39,662 │          256 │        768 │       41,645 │     $16.42 │
│ 2025-05-28   │    155 │  21,693 │          128 │        512 │       22,488 │      $8.36 │
├──────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┤
│ Total        │ 11,174 │ 720,366 │          896 │      2,304 │      734,740 │    $336.47 │
└──────────────┴────────┴─────────┴──────────────┴────────────┴──────────────┴────────────┘

╭───────────────────────────────────────────────╮
│                                               │
│  Claude Code Token Usage Report - By Session  │
│                                               │
╰───────────────────────────────────────────────╯

┌─────────────┬────────────┬────────┬─────────┬──────────────┬────────────┬──────────────┬────────────┬───────────────┐
│ Project     │ Session    │ Input  │ Output  │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │ Last Activity │
├─────────────┼────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┼───────────────┤
│ myproject   │ session-1  │  4,512 │ 350,846 │          512 │      1,024 │      356,894 │    $156.40 │ 2025-05-24    │
├─────────────┼────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┼───────────────┤
│ myproject   │ session-2  │  2,775 │ 186,645 │          256 │        768 │      190,444 │     $98.45 │ 2025-05-25    │
├─────────────┼────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┼───────────────┤
│ Total       │            │ 11,174 │ 720,445 │          768 │      1,792 │      734,179 │    $336.68 │               │
└─────────────┴────────────┴────────┴─────────┴──────────────┴────────────┴──────────────┴────────────┴───────────────┘

• Claude Code usage history files (~/.claude/projects/**/*.jsonl)

MIT

@ryoppippi

This tool was inspired by this excellent article by @milliondev about tracking Claude Code usage costs. The article demonstrates how to analyze Claude Code's local JSONL files using DuckDB to understand token usage patterns and costs.

While the original approach uses DuckDB for analysis, this tool provides a more accessible CLI interface with the same core functionality - analyzing the same JSONL files that Claude Code stores locally to give you insights into your usage patterns and costs.

Thanks to @milliondev for the original concept and approach to Claude Code usage analysis.