Analyze your Claude Code token usage and costs from local JSONL files — incredibly fast and informative!
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
bunxinstead ofnpxfor a massive speed improvement!
Since ccusage has such a small bundle size, installation is entirely optional:
npm install -g ccusage# 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
ccusage statusline # Compact status line for hooks (Beta)
# 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
# Compact mode for screenshots/sharing
ccusage --compact # Force compact table mode
ccusage monthly --compact # Compact monthly report- 📊 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 - 🚀 Statusline Integration: Compact usage display for Claude Code status bar hooks (Beta)
- 🤖 Model Tracking: See which Claude models you're using (Opus, Sonnet, etc.)
- 📊 Model Breakdown: View per-model cost breakdown with
--breakdownflag - 📅 Date Filtering: Filter reports by date range using
--sinceand--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
- 📸 Compact Mode: Use
--compactflag to force compact table layout, perfect for screenshots and sharing - 📋 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
--instancesflag and filter by specific projects - 🌍 Timezone Support: Configure timezone for date grouping with
--timezoneoption - 🌐 Locale Support: Customize date/time formatting with
--localeoption (e.g., en-US, ja-JP, de-DE) - ⚙️ Configuration Files: Set defaults with JSON configuration files, complete with IDE autocomplete and validation
- 🚀 Ultra-Small Bundle: Unlike other CLI tools, we pay extreme attention to bundle size - incredibly small even without minification!
Full documentation is available at ccusage.com
Check out ccusage: The Claude Code cost scorecard that went viral
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.