ccusage - Claude Code Usage Tracker

Track your Claude Code usage, costs, and savings across different subscription plans.

Inspired by the original ccusage tool from "The COST of Claude Code" YouTube video

Features

• 📊 Daily Usage: View token usage and costs by day
• 📅 Monthly Usage: Track monthly spending and projections
• ⏱️ 5-Hour Blocks: Monitor usage blocks with live tracking
• 📁 Project Sessions: Analyze usage by project/session
• 💰 Cost Analysis: Compare savings across subscription plans
• 🚀 Cache Efficiency: Track how much cache is saving you
• 📈 Live Monitoring: Real-time block usage tracking

Installation

# Install globally
npm install -g ccusage

# Or run without installing using bunx (recommended)
bunx ccusage

Usage

Default (Daily View)

ccusage
# or
ccusage daily

Shows last 7 days of usage with cost analysis.

Monthly View

ccusage monthly

Shows usage aggregated by month with comparisons.

Blocks View

ccusage blocks

Shows 5-hour usage blocks (Claude's rate limiting windows).

Live Block Monitoring

ccusage blocks --live

Real-time monitoring of current block usage with projections.

Session/Project View

ccusage session

Shows usage broken down by project with cache efficiency metrics.

Command Options

Daily Command

• -d, --days <number>: Number of days to show (default: 7)

Blocks Command

• --live: Enable live monitoring mode

Understanding the Output

Token Types

• Input Tokens: Tokens sent to Claude
• Output Tokens: Tokens generated by Claude
• Cache Read: Tokens read from cache (90% cheaper)
• Cache Write: Tokens written to cache

Cost Analysis

The tool shows:

• Actual token costs at pay-as-you-go rates
• Savings when using Claude Max plans
• Cache efficiency percentage
• Projected monthly costs

5-Hour Blocks

Claude uses 5-hour windows for rate limiting. The blocks view helps you:

• Track usage within rate limit windows
• See burn rate per hour
• Project total block cost
• Monitor active blocks in real-time

Requirements

• Node.js 16+
• Claude Code must be installed and used at least once
• Access to ~/.claude/projects/ directory

How It Works

ccusage reads Claude's log files from ~/.claude/projects/*/claude.jsonl and calculates costs based on current model pricing. It tracks:

1. Token usage per request
2. Model used for each request
3. Cache efficiency
4. Timestamps for aggregation

Privacy

All data is read locally from your machine. No data is sent to external servers.

Inspired By

This tool is inspired by the original ccusage tool mentioned in "The COST of Claude Code" YouTube video. It provides similar functionality for tracking Claude Code usage and costs.

License

MIT