Skip to main content
ccusage CLI showing daily token usage report

​
What is ccusage?

ccusage is a CLI tool that analyzes Claude Code token usage and costs from local JSONL files. Track your daily, monthly, and session-based usage with beautiful tables and comprehensive reporting.

​
Key features

Daily and monthly reports

View token usage and costs aggregated by date or month with beautiful table formatting

Session tracking

Analyze usage grouped by conversation sessions to understand project-level costs

5-hour billing blocks

Track usage within Claude’s billing windows with active block monitoring

Model breakdown

See which Claude models you’re using (Opus, Sonnet) with per-model cost analysis

Cache token support

Tracks cache creation and cache read tokens separately for accurate cost tracking

JSON output

Export data in structured JSON format for programmatic consumption and automation

Project analysis

Group usage by project with --instances flag and filter by specific projects

MCP integration

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

​
Why ccusage?

  • Ultra-small bundle size - Incredibly lightweight even without minification, perfect for instant execution with npx
  • Offline mode - Use pre-cached pricing data without network connectivity (Claude models only)
  • Smart tables - Automatic compact mode for narrow terminals with essential columns
  • 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)
  • Configuration files - Set defaults with JSON configuration files, complete with IDE autocomplete and validation

​
ccusage family

ccusage is part of a family of usage analysis tools:

​
Next steps

Installation

Install ccusage with your preferred package manager

Quick start

Get started with your first usage report

Build docs developers (and LLMs) love

Get started for freeTalk to us