https://github.com/ryoppippi/ccusage
A CLI tool for analyzing Claude Code usage from local JSONL files.
https://github.com/ryoppippi/ccusage
Last synced: about 1 month ago
JSON representation
A CLI tool for analyzing Claude Code usage from local JSONL files.
- Host: GitHub
- URL: https://github.com/ryoppippi/ccusage
- Owner: ryoppippi
- License: mit
- Created: 2025-05-29T16:56:50.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-08-24T22:14:48.000Z (about 1 month ago)
- Last Synced: 2025-08-25T01:36:25.549Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://ccusage.com/
- Size: 5.52 MB
- Stars: 7,255
- Watchers: 18
- Forks: 215
- Open Issues: 42
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yaml
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code - ccusage
- awesome-claude - ccusage - 7.2k⭐ - CLI tool for analyzing Claude Code usage from JSONL files (Claude Code Ecosystem / Monitoring & Analytics)
- awesome - ryoppippi/ccusage - A CLI tool for analyzing Claude Code usage from local JSONL files. (TypeScript)
- awesome-claude-code - `CC Usage`
- awesome-claude-code - **ccusage**
README
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 ([](https://packagephobia.com/result?p=ccusage)), you can run it directly without installation:
```bash
# 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:
```bash
npm install -g ccusage
```
## Usage
```bash
# 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
```
## 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/)**
## Sponsors
### Featured Sponsor
Check out [ccusage: The Claude Code cost scorecard that went viral](https://www.youtube.com/watch?v=Ak6qpQ5qdgk)
## Claude Code Resources
[`ClaudeLog`](https://claudelog.com) by [InventorBlack](https://www.reddit.com/user/inventor_black/)
A comprehensive knowledge base with detailed breakdowns of advanced topics, including:
- Advanced [mechanics](https://claudelog.com/mechanics/you-are-the-main-thread/) and [CLAUDE.md best practices](https://claudelog.com/mechanics/claude-md-supremacy).
- Practical technique guides for [plan mode](https://claudelog.com/mechanics/plan-mode), [ultrathink](https://claudelog.com/faqs/what-is-ultrathink/), and [sub-agents](https://claudelog.com/mechanics/task-agent-tools/).
- Concepts like [agent-first design](https://claudelog.com/mechanics/agent-first-design/), [agent engineering](https://claudelog.com/mechanics/agent-engineering/), and [humanizing agents](https://claudelog.com/mechanics/humanising-agents/).
- [Configuration guides](https://claudelog.com/configuration).
## Star History
## License
[MIT](LICENSE) © [@ryoppippi](https://github.com/ryoppippi)