ccusage

ccusage

Analyze your Claude Code token usage and costs from local JSONL files — incredibly fast and informative!

Installation

Quick Start (Recommended)

Thanks to ccusage's incredibly small bundle size (), you can run it directly without installation:

# Using bunx (recommended for speed)
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

💡 Tip: We recommend using bunx instead of npx for a massive speed improvement!

Local Installation (Optional)

Since ccusage has such a small bundle size, installation is entirely optional:

npm install -g ccusage

Usage

# Basic usage
ccusage          # Show daily report (default)
ccusage daily    # Daily token usage and costs
ccusage monthly  # Monthly aggregated report
ccusage session  # Usage by conversation session
ccusage blocks   # 5-hour billing windows

# Live monitoring
ccusage blocks --live  # Real-time usage dashboard

# Filters and options
ccusage daily --since 20250525 --until 20250530
ccusage daily --json  # JSON output
ccusage daily --breakdown  # Per-model cost breakdown
ccusage daily --timezone UTC  # Use UTC timezone
ccusage daily --locale ja-JP  # Use Japanese locale for date/time formatting

# Project analysis
ccusage daily --instances  # Group by project/instance
ccusage daily --project myproject  # Filter to specific project
ccusage daily --instances --project myproject --json  # Combined usage

Features

• 📊 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
• ⏰ 5-Hour Blocks Report: Track usage within Claude's billing windows with active block monitoring
• 📈 Live Monitoring: Real-time dashboard showing active session progress, token burn rate, and cost projections with blocks --live
• 🤖 Model Tracking: See which Claude models you're using (Opus, Sonnet, etc.)
• 📊 Model Breakdown: View per-model cost breakdown with --breakdown flag
• 📅 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 with automatic responsive layout
• 📱 Smart Tables: Automatic compact mode for narrow terminals (< 100 characters) with essential columns
• 📋 Enhanced Model Display: Model names shown as bulleted lists for better readability
• 📄 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
• 🌐 Offline Mode: Use pre-cached pricing data without network connectivity with --offline (Claude models only)
• 🔌 MCP Integration: Built-in Model Context Protocol server for integration with other tools
• 🏗️ Multi-Instance Support: Group usage by project with --instances flag and filter by specific projects
• 🌍 Timezone Support: Configure timezone for date grouping with --timezone option
• 🌐 Locale Support: Customize date/time formatting with --locale option (e.g., en-US, ja-JP, de-DE)
• 🚀 Ultra-Small Bundle: Unlike other CLI tools, we pay extreme attention to bundle size - incredibly small even without minification!

Documentation

Full documentation is available at ccusage.com

Sponsors

Featured Sponsor

Check out these 47 Claude Code ProTips from Greg Baugues.

Claude Code Resources

ClaudeLog   by   InventorBlack A comprehensive knowledge base with detailed breakdowns of advanced topics, including:

• Advanced mechanics and CLAUDE.md best practices.
• Practical technique guides for plan mode, ultrathink, and sub-agents.
• Concepts like agent-first design, agent engineering, and humanizing agents.
• Configuration guides.

Star History

License

MIT © @ryoppippi