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
--sinceand--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
- 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.
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 --jsonccusage 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 Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30 │ 277 │ 31,456 │ 31,733 │ $17.45 │
│ 2025-05-29 │ 959 │ 39,662 │ 40,621 │ $16.37 │
│ 2025-05-28 │ 155 │ 21,693 │ 21,848 │ $8.33 │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ Total │ 11,174 │ 720,366 │ 731,540 │ $336.17 │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘
╭───────────────────────────────────────────────╮
│ │
│ Claude Code Token Usage Report - By Session │
│ │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ Project / Session │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │ Last Activity │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project │ 2,775 │ 186,645 │ 189,420 │ $98.40 │ 2025-05-26 │
│ └─ session-abc123... │ │ │ │ │ │
│ another-project │ 1,063 │ 41,421 │ 42,484 │ $20.08 │ 2025-05-29 │
│ └─ session-def456... │ │ │ │ │ │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ Total │ 11,174 │ 720,445 │ 731,619 │ $336.38 │ │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘
- Bun runtime
- Claude Code usage history files (
~/.claude/projects/**/*.jsonl)
# Run tests
bun test
# Type check
bun run typecheck
# Lint
bun run lint
# Format code
bun run formatccusage/
├── commands/
│ ├── daily.ts # Daily report command
│ └── session.ts # Session report command
├── data-loader.ts # JSONL data loading logic
├── index.ts # CLI entry point
├── logger.ts # Logger configuration
├── utils.ts # Shared utilities
└── package.json
MIT
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.