Ccusage: CLI tool for analyzing Claude Code usage

4 hours ago 3

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.

What is ccusage (by NotebookLM)

Podcact Claude.Code.CLI.ccusage.mov

what-is-ccusage-jp.mov

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
📅 Monthly Report: View token usage and costs aggregated by month
💬 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/month/session
🔄 Cache Token Support: Tracks and displays cache creation and cache read tokens separately

⚠️ This is NOT an official Claude tool - it's an independent community project that analyzes locally stored usage data.

Cost calculations are estimates only and may not reflect actual billing:

Costs shown are virtual/estimated based on token counts and model pricing data
Actual costs may vary due to pricing changes, special rates, or billing adjustments
We do not guarantee the accuracy of calculated costs
For official billing information, always refer to your Claude account dashboard

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.

Quick Start (Recommended)

Run directly without installation:

# Using npx npx ccusage@latest # Using bunx bunx ccusage # Using pnpm pnpm dlx ccusage # Using Deno with security flags deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

# 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 # Control cost calculation mode ccusage daily --mode auto # Use costUSD when available, calculate otherwise (default) ccusage daily --mode calculate # Always calculate costs from tokens ccusage daily --mode display # Always show pre-calculated costUSD values

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

Shows token usage and costs aggregated by month:

# Show all monthly usage ccusage monthly # Filter by date range ccusage monthly --since 20250101 --until 20250531 # Use custom Claude data directory ccusage monthly --path /custom/path/to/.claude # Output in JSON format ccusage monthly --json # Control cost calculation mode ccusage monthly --mode auto # Use costUSD when available, calculate otherwise (default) ccusage monthly --mode calculate # Always calculate costs from tokens ccusage monthly --mode display # Always show pre-calculated costUSD values

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 # Control cost calculation mode ccusage session --mode auto # Use costUSD when available, calculate otherwise (default) ccusage session --mode calculate # Always calculate costs from tokens ccusage session --mode display # Always show pre-calculated costUSD values

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
-m, --mode <mode>: Cost calculation mode: auto (default), calculate, or display
-d, --debug: Show pricing mismatch information for debugging
--debug-samples <number>: Number of sample discrepancies to show in debug output (default: 5)
-h, --help: Display help message
-v, --version: Display version

auto (default): Uses pre-calculated costUSD values when available, falls back to calculating costs from token counts using model pricing
calculate: Always calculates costs from token counts using model pricing, ignores any pre-calculated costUSD values
display: Always uses pre-calculated costUSD values only, shows $0.00 for entries without pre-calculated costs

MCP (Model Context Protocol) Support

Exposes usage data through Model Context Protocol for integration with other tools:

# Start MCP server with stdio transport (for local integration) ccusage mcp # Start MCP server with HTTP stream transport (for remote access) ccusage mcp --type http --port 8080 # Control cost calculation mode ccusage mcp --mode calculate

The MCP server supports both stdio and HTTP stream transports:

stdio (default): Best for local integration where the client directly spawns the process
HTTP stream: Best for remote access when you need to call the server from another machine or network location

Available MCP tools:

daily: Returns daily usage reports (accepts since, until, mode parameters)
session: Returns session usage reports (accepts since, until, mode parameters)

Claude Desktop Configuration Example

To use ccusage MCP with Claude Desktop, add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "ccusage": { "command": "npx", "args": ["ccusage@latest", "mcp"], "env": {} } } }

Or if you have ccusage installed globally:

{ "mcpServers": { "ccusage": { "command": "ccusage", "args": ["mcp"], "env": {} } } }

After adding this configuration, restart Claude Desktop. You'll then be able to use the ccusage tools within Claude to analyze your usage data.

╭──────────────────────────────────────────╮ │ │ │ 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.

Read Entire Article