ccusage

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

English

https://github.com/user-attachments/assets/7a00f2f3-82a7-41b6-a8da-e04b76b5e35a

日本語

https://github.com/user-attachments/assets/db09fc06-bf57-4d37-9b06-514851bcc1d0

Motivation

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! 😊

Features

• 📊 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

Important Disclaimer

⚠️ 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

Limitations

• 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.

Installation

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

Local Installation

# Install globally with npm
npm install -g ccusage

# Install globally with bun
bun install -g ccusage

# Then run
ccusage daily

Development Setup

# 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]

Usage

Daily Report (Default)

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.

Session Report

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

Options

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

Cost Calculation Modes

• 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.

Output Example

Daily Report

╭──────────────────────────────────────────╮
│                                          │
│  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 │
└──────────────┴────────┴─────────┴──────────────┴────────────┴──────────────┴────────────┘

Session Report

╭───────────────────────────────────────────────╮
│                                               │
│  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 │               │
└─────────────┴────────────┴────────┴─────────┴──────────────┴────────────┴──────────────┴────────────┴───────────────┘

Requirements

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

License

MIT

Author

@ryoppippi

Inspiration

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.

Acknowledgments

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