ccusage

<div align="center"> <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/logo.svg" alt="ccusage logo" width="256" height="256"> <h1>ccusage</h1> </div> <p align="center"> <a href="https://socket.dev/api/npm/package/ccusage"><img src="https://socket.dev/api/badge/npm/package/ccusage" alt="Socket Badge" /></a> <a href="https://npmjs.com/package/ccusage"><img src="https://img.shields.io/npm/v/ccusage?color=yellow" alt="npm version" /></a> <a href="https://tanstack.com/stats/npm?packageGroups=%5B%7B%22packages%22:%5B%7B%22name%22:%22ccusage%22%7D%5D%7D%5D&range=30-days&transform=none&binType=daily&showDataMode=all&height=400"><img src="https://img.shields.io/npm/dt/ccusage" alt="NPM Downloads" /></a> <a href="https://packagephobia.com/result?p=ccusage"><img src="https://packagephobia.com/badge?p=ccusage" alt="install size" /></a> <a href="https://deepwiki.com/ryoppippi/ccusage"><img src="https://img.shields.io/badge/DeepWiki-ryoppippi%2Fccusage-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="DeepWiki"></a>  <a href="https://github.com/hesreallyhim/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code" /></a> </p> <div align="center"> <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/screenshot.png"> </div> > Analyze your Claude Code token usage and costs from local JSONL files — incredibly fast and informative! ## ccusage Family ### 📊 [ccusage](https://www.npmjs.com/package/ccusage) - Claude Code Usage Analyzer The main CLI tool for analyzing Claude Code usage from local JSONL files. Track daily, monthly, and session-based usage with beautiful tables and live monitoring. ### 🤖 [@ccusage/codex](https://www.npmjs.com/package/@ccusage/codex) - OpenAI Codex Usage Analyzer 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. ### 🔌 [@ccusage/mcp](https://www.npmjs.com/package/@ccusage/mcp) - MCP Server Integration 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 ### Quick Start (Recommended) Thanks to ccusage's incredibly small bundle size ([![install size](https://packagephobia.com/badge?p=ccusage)](https://packagephobia.com/result?p=ccusage)), you can run it directly without installation: ```bash # Recommended - always include @latest to ensure you get the newest version npx ccusage@latest bunx ccusage # Alternative package runners pnpm dlx ccusage pnpx ccusage # Using deno (with security flags) deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest ``` > 💡 **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. ### Related Tools #### Codex CLI Analyze OpenAI Codex usage with our companion tool [@ccusage/codex](https://www.npmjs.com/package/@ccusage/codex): ```bash # Recommended - always include @latest npx @ccusage/codex@latest bunx @ccusage/codex@latest # ⚠️ MUST include @latest with bunx # Alternative package runners pnpm dlx @ccusage/codex pnpx @ccusage/codex # Using deno (with security flags) deno run -E -R=$HOME/.codex/ -S=homedir -N='raw.githubusercontent.com:443' npm:@ccusage/codex@latest ``` > ⚠️ **Critical for bunx users**: Bun 1.2.x's bunx prioritizes binaries matching the package name suffix when given a scoped package. For `@ccusage/codex`, it looks for a `codex` binary in PATH first. If you have an existing `codex` command installed (e.g., GitHub Copilot's codex), that will be executed instead. **Always use `bunx @ccusage/codex@latest` with the version tag** to force bunx to fetch and run the correct package. #### MCP Server Integrate ccusage with Claude Desktop using [@ccusage/mcp](https://www.npmjs.com/package/@ccusage/mcp): ```bash # Start MCP server for Claude Desktop integration npx @ccusage/mcp@latest --type http --port 8080 ``` This enables real-time usage tracking and analysis directly within Claude Desktop conversations. ## Usage ```bash # Basic usage npx ccusage # Show daily report (default) npx ccusage daily # Daily token usage and costs npx ccusage monthly # Monthly aggregated report npx ccusage session # Usage by conversation session npx ccusage blocks # 5-hour billing windows npx ccusage statusline # Compact status line for hooks (Beta) # Live monitoring npx ccusage blocks --live # Real-time usage dashboard # Filters and options npx ccusage daily --since 20250525 --until 20250530 npx ccusage daily --json # JSON output npx ccusage daily --breakdown # Per-model cost breakdown npx ccusage daily --timezone UTC # Use UTC timezone npx ccusage daily --locale ja-JP # Use Japanese locale for date/time formatting # Project analysis npx ccusage daily --instances # Group by project/instance npx ccusage daily --project myproject # Filter to specific project npx ccusage daily --instances --project myproject --json # Combined usage # Compact mode for screenshots/sharing npx ccusage --compact # Force compact table mode npx ccusage monthly --compact # Compact monthly report ``` ## 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` - 🚀 **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](https://ccusage.com/)** ## Development Setup ### Using Nix (Recommended for Contributors) For contributors and developers working on ccusage, we provide a Nix flake-based development environment: ```bash # Clone the repository git clone https://github.com/ryoppippi/ccusage.git cd ccusage # Allow direnv (automatically loads Nix environment) direnv allow # Or manually enter the development shell nix develop ``` 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 ### Featured Sponsor Check out [ccusage: The Claude Code cost scorecard that went viral](https://www.youtube.com/watch?v=Ak6qpQ5qdgk) <p align="center"> <a href="https://www.youtube.com/watch?v=Ak6qpQ5qdgk"> <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/ccusage_thumbnail.png" alt="ccusage: The Claude Code cost scorecard that went viral" width="600"> </a> </p> <p align="center"> <a href="https://github.com/sponsors/ryoppippi"> <img src="https://cdn.jsdelivr.net/gh/ryoppippi/sponsors@main/sponsors.svg"> </a> </p> ## Star History <a href="https://www.star-history.com/#ryoppippi/ccusage&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" /> </picture> </a> ## License [MIT](LICENSE) © [@ryoppippi](https://github.com/ryoppippi)