CLI tool that analyzes your Claude Code session data locally -- token usage, costs, efficiency, and coding patterns. No API calls, no cloud, just your local .jsonl files.
- Interactive HTML Dashboard -- Vue 3 single-file app with 6 pages (Overview, Trends, Projects, Sessions, Heatmap, Wrapped), dark/light theme, EN/ZH i18n
- Terminal Reports -- rich tables via comfy-table, works anywhere
- Heatmap -- GitHub-style terminal activity heatmap (
░▒▓█) - Wrapped -- Spotify-style annual summary with developer archetypes
- Project Drill-Down -- rank projects by cost, filter by name, drill into sessions and turns
- Trend Analysis -- daily/monthly cost trends, month-over-month comparison
- Context Collapse Detection -- identify sessions where context was compacted and assess risk
- Code Attribution -- track Claude's code contributions per session
- Efficiency Metrics -- output ratio, cost per turn, cache savings analysis
- Session Metadata Mining -- titles, tags, mode, branch, errors, speculation accepts
- Dual-Path Validation -- independent raw JSON counter cross-checks the pipeline
- JSON Export -- all subcommands support
--format jsonfor tool integration - Parallel Processing -- rayon-powered parallel parsing (3.9x speedup on large datasets)
- 164+ Tests -- comprehensive coverage across both crates
Quick install (macOS / Linux):
curl -fsSL https://raw.githubusercontent.com/LokiQ0713/cc-token-usage/master/install.sh | shVia npm:
npx cc-token-usage # zero-install, always latest
npm install -g cc-token-usage # global installVia cargo:
cargo install cc-token-usagecc-token-usage update # download and replace
cc-token-usage update --check # check only, don't downloadInstall as a skill so Claude can run it for you when you ask "how much have I spent?":
npx skills add LokiQ0713/cc-token-usage -g -yDefault: prints terminal summary + opens HTML dashboard in browser:
cc-token-usage| Command | Description |
|---|---|
overview |
Overall usage summary across all projects |
project |
Project-level breakdown, ranked by cost |
session |
Single session detail with turn-by-turn analysis |
trend |
Daily/monthly usage trends |
heatmap |
GitHub-style terminal activity heatmap |
wrapped |
Annual "Wrapped" summary with developer archetype |
validate |
Cross-validate token counts against raw JSONL |
update |
Self-update the binary |
# HTML dashboard only
cc-token-usage --format html
# JSON export
cc-token-usage --format json
# All projects ranked by cost
cc-token-usage project --top 0
# Filter a specific project
cc-token-usage project --name "my-project"
# Latest session details
cc-token-usage session --latest
# Monthly breakdown
cc-token-usage trend --group-by month
# Daily trend (last 30 days)
cc-token-usage trend --days 30
# Terminal heatmap (last year)
cc-token-usage heatmap
# Heatmap for all history
cc-token-usage heatmap --days 0
# Annual wrapped summary
cc-token-usage wrapped
# Wrapped for a specific year
cc-token-usage wrapped --year 2025
# Validate token counting accuracy
cc-token-usage validate --failures-onlyClaude Code Token Report
2026-01-11 ~ 2026-03-21
238 conversations, 19,720 rounds of back-and-forth
Claude read 1,913,274,753 tokens
Claude wrote 4,776,580 tokens
Cache saved you $7,884.80 (90% of reads were free)
All that would cost $1,554.50 at API rates
Model Wrote Rounds Cost
---------------------------------------------------------
opus-4-6 4,005,415 15,219 $1,435.47
sonnet-4-6 479,336 1,533 $73.22
haiku-4-5 254,469 2,322 $19.26
Top Projects Sessions Turns Cost
-------------------------------------------------------------------
~/cc 80 6134 $606.15
~/Desktop/claude/statusline/config 2 5603 $439.16
The --format html flag generates a self-contained single-file HTML dashboard (370KB, zero network dependencies). It includes:
- Overview -- aggregate stats, model breakdown, per-agent costs, usage insights
- Trends -- daily cost chart with month-over-month comparison
- Projects -- all projects ranked by cost, click to drill into sessions
- Sessions -- session list with metadata (title, tags, mode, branch)
- Heatmap -- interactive activity heatmap
- Wrapped -- annual summary with developer archetype classification
Built with Vue 3 + TailwindCSS + Chart.js. Supports dark/light theme toggle and EN/ZH language switching.
Reads ~/.claude/projects/ directly. Parses every JSONL session file, including subagent files (both legacy flat-style and new nested-style). Validates data, deduplicates by requestId, attributes orphan agents, detects context compactions.
Parsing library: The cc-session-jsonl crate handles all JSONL parsing independently -- 23 entry types, 3 file layout formats, forward-compatible with Unknown variant. Available as a standalone crate on crates.io.
Pricing: Uses official Anthropic rates from platform.claude.com. Distinguishes 5-minute vs 1-hour cache TTL for accurate cost calculation.
Optional. Create ~/.config/cc-token-usage/config.toml to override model pricing:
[pricing_override.claude-opus-4-6]
base_input = 5.0
cache_write_5m = 6.25
cache_write_1h = 10.0
cache_read = 0.50
output = 25.0crates/
cc-session-jsonl/ # Pure JSONL parsing library (98 tests)
cc-token-usage/ # Analysis CLI (61+ tests)
frontend/ # Vue 3 + Vite + TailwindCSS dashboard
npm-package/ # npm binary wrapper
cargo build
cargo test --workspace --all-features # 164+ tests
cargo clippy --workspace --all-features -- -D warnings
cargo fmtcd frontend
npm install
npm run dev # dev server with HMR
npm run build # build single-file HTML → dist/index.htmlAfter building, the Rust binary embeds frontend/dist/index.html via include_str! -- no separate file needed at runtime.
Rust (serde, clap, chrono, comfy-table, rayon) + Vue 3 + TailwindCSS + Chart.js
MIT