ccusage - Claude Code Usage Analysis Tool

Project Overview

ccusage is a CLI tool for analyzing usage data from local Claude Code JSONL files. The project was developed by @ryoppippi, inspired by an article on tracking Claude Code usage costs.

Key Features

📊 Multiple Report Types

• Daily Report: Summarizes token usage and costs by date
• Monthly Report: Summarizes token usage and costs by month
• Session Report: Displays usage grouped by conversation session
• 5-Hour Block Report: Reports based on 5-hour billing windows
• Status Line: A compact status line for hooks (Beta)

🎯 Powerful Filtering and Analysis Capabilities

• Date Filtering: Filter reports by date range using --since and --until
• Project Analysis: Group by project/instance, supports filtering for specific projects
• Model Cost Breakdown: Cost breakdown for each model
• Timezone and Localization: Supports UTC timezone and Japanese localization format

🎨 Aesthetic Output and Display

• Displays in colorful table format with automatic responsive layout
• Smart Table: Automatic compact mode for narrow terminals (<100 characters), showing essential columns
• Compact Mode: Force compact table layout using the --compact flag, ideal for screenshots and sharing
• Enhanced Model Display: Model names displayed as a bulleted list for improved readability

💰 Cost Tracking Features

• Displays daily/monthly/session costs in USD
• Cached Token Support: Separately tracks and displays cache creation and cache read tokens
• Offline Mode: Use --offline to utilize pre-cached pricing data when offline (Claude models only)

⚡ Real-time Monitoring

• Real-time usage dashboard
• Live monitoring: ccusage blocks --live

Installation and Usage

Quick Start (No Installation Required)

Due to ccusage's minimal package size, it can be run directly without installation:

# Using bunx (recommended, faster)
bunx ccusage

# Using npx
npx ccusage@latest

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

Global Installation

# Global installation with npm
npm install -g ccusage

# Global installation with bun
bun install -g ccusage

# Then run
ccusage

Development Environment

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

Basic Usage

Daily Report

# Show all daily usage
ccusage daily

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

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

# Output in JSON format
ccusage daily --json

# Cost breakdown per model
ccusage daily --breakdown

# Use UTC timezone
ccusage daily --timezone UTC

# Use Japanese localization
ccusage daily --locale ja-JP

Project Analysis

# Group by project/instance
ccusage daily --instances

# Filter to a specific project
ccusage daily --project myproject

# Combined usage
ccusage daily --instances --project myproject --json

Session Report

# Show all sessions
ccusage session

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

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

# Output in JSON format
ccusage session --json

Real-time Monitoring

# Real-time usage dashboard
ccusage blocks --live

# 5-hour billing window
ccusage blocks

# Status line (Beta)
ccusage statusline

Compact Mode

# Force compact table mode
ccusage --compact

# Compact monthly report
ccusage monthly --compact

Command Options

All commands support the following options:

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

Output Examples

Daily Report Output

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

Session Report Output

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

Technical Architecture

Dependency Requirements

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

Project Structure

ccusage/
├── 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          # Logging configuration
├── utils.ts           # Shared utilities
└── package.json

Development and Testing

# Run tests
bun test

# Type check
bun run typecheck

# Lint code
bun run lint

# Format code
bun run format

Integration Features

🔌 MCP Integration

Built-in Model Context Protocol server for integration with other tools

Summary

ccusage is a powerful and easy-to-use CLI tool specifically designed for Claude Code users to analyze and track token usage and associated costs. Its lightweight design, rich feature set, and aesthetic output make it an ideal choice for developers looking to optimize their Claude Code usage and manage costs.