ccusage

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

ccusage Family

$3

The main CLI tool for analyzing Claude Code usage from local JSONL files. Track daily, monthly, and session-based usage with beautiful tables.

$3

Companion tool for analyzing OpenAI Codex usage. Same powerful features as ccusage but tailored for Codex users, including GPT-5 support and 1M token context windows.

$3

Companion tool for analyzing OpenCode usage. Track token usage and costs from OpenCode sessions with the same reporting capabilities as ccusage.

$3

Companion tool for analyzing pi-agent session usage. Track token usage and costs from your pi-agent sessions with daily, monthly, and session-based reports.

$3

Companion tool for analyzing Amp session usage. Track token usage, costs, and credits from your Amp CLI sessions with daily, monthly, and session-based reports.

$3

Model Context Protocol server that exposes ccusage data to Claude Desktop and other MCP-compatible tools. Enable real-time usage tracking directly in your AI workflows.

Installation

$3

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

``bash


Recommended - always include @latest to ensure you get the newest version

> 💡 Important: We strongly recommend using @latest suffix with npx (e.g., npx ccusage@latest) to ensure you're running the most recent version with the latest features and bug fixes.

$3

`bash
npx @ccusage/codex@latest # OpenAI Codex usage tracking
npx @ccusage/opencode@latest # OpenCode usage tracking
npx @ccusage/pi@latest # Pi-agent usage tracking
npx @ccusage/amp@latest # Amp usage tracking
npx @ccusage/mcp@latest # MCP Server
`

Usage

`bash


Basic usage

- 📊 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
- 🚀 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 --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
- 📸 Compact Mode: Use --compact flag 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 --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)
- ⚙️ 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!

Documentation

Full documentation is available at ccusage.com

Development Setup

$3

For contributors and developers working on ccusage, we provide a Nix flake-based development environment:

`bash


Clone the repository

This ensures consistent tooling versions across all contributors and CI systems. The development environment is defined in flake.nix` and automatically activated via direnv when entering the project directory.

Sponsors

$3

Check out ccusage: The Claude Code cost scorecard that went viral

Star History

License

MIT © @ryoppippi