ccusage tells you how much. claude-usage-analyzer tells you why, and what to do about it.
claude-usage-analyzer (ccwhy) tells you exactly where your Claude Code tokens are going and how to cut usage. It analyzes your Claude Code session history, identifies the biggest token sinks (long contexts, repeated tool calls, verbose configs), and recommends specific optimizations. Think of it as an AI coding token usage debugger: a Claude Code session analyzer focused on Claude Code token optimization and Claude Code cost reduction.
A Claude Code usage debugger written in Rust. Parses your local session data, identifies where your tokens actually went, and gives you actionable suggestions to reduce waste.
- Reduce Claude Code monthly bill by finding token sinks
- Debug why a Claude Code session burned through context window
- Compare token usage across Claude Code projects
- Find which tools or hooks waste the most tokens
- Optimize CLAUDE.md to reduce per-turn token cost
- Audit Claude Code usage for a team or organization
- Identify when /compact would have saved money
Text version
claude-usage-analyzer - Claude Code Usage Debugger
Why did your tokens burn? What to do about it.
Overview
Sessions: 187 | Total tokens: 3.3B | Equivalent cost: $6,739
(Cost shown is API-equivalent. Max subscribers pay a flat rate.)
Controllable Token Sinks (what you can reduce)
Total controllable: 93.7M (2.8% of all tokens)
███████████████████░ 92.5% 86.7M Cache creation (CLAUDE.md, MCP, system prompt)
→ Large initial context. Trim unused CLAUDE.md rules or MCP tools.
█░░░░░░░░░░░░░░░░░░ 6.6% 6.2M Model output (Claude's responses)
████████░░░░░░░░░░░░ 40.2% Tool: Bash (7,074 calls, 40% of tool calls)
→ Many shell commands. Long outputs eat tokens. Pipe to head/tail.
Fixed Overhead (normal, not actionable)
97.2% 3.2B Cache reads (context re-read every turn - normal, cheap at $1.5/M)
Anomaly Sessions (33 sessions burning >2x average rate)
⚡ 710,300 tok/min (3.9x avg) ~/projects/my-app
⚡ 603,147 tok/min (3.3x avg) /tmp/sandbox
Peak vs Off-Peak Hours
Peak (Mon-Fri 5-11am PT): 42 sessions, avg 21.9M tokens/session
Off-peak: 145 sessions, avg 16.5M tokens/session
Peak sessions use 1.3x more tokens on average.
Suggestions
1. 86 session(s) exceeded 30 turns. Use /compact to reduce context buildup.
2. 840 subagent calls. Each duplicates full context. Use Grep/Glob directly.
brew install SingggggYee/tap/claude-usage-analyzercargo install claude-usage-analyzerGrab the latest release from Releases:
# macOS Apple Silicon
curl -L https://github.com/SingggggYee/claude-usage-analyzer/releases/latest/download/claude-usage-analyzer-macos-aarch64.tar.gz | tar xz
./claude-usage-analyzer
# macOS Intel
curl -L https://github.com/SingggggYee/claude-usage-analyzer/releases/latest/download/claude-usage-analyzer-macos-x86_64.tar.gz | tar xz
# Linux x86_64
curl -L https://github.com/SingggggYee/claude-usage-analyzer/releases/latest/download/claude-usage-analyzer-linux-x86_64.tar.gz | tar xzgit clone https://github.com/SingggggYee/claude-usage-analyzer
cd claude-usage-analyzer
cargo build --release
./target/release/claude-usage-analyzerAlso available as a Claude Code skill: Claude Usage Analyzer on ClawHub
# Full report (last 30 days)
claude-usage-analyzer
# Last 7 days
claude-usage-analyzer report --days 7
# All time
claude-usage-analyzer report --days 0
# Top sessions by cost
claude-usage-analyzer sessions
# Session detail
claude-usage-analyzer session <session-id-prefix>Where your tokens actually go. Not just totals - broken down by:
- Cache reads vs cache creation vs output
- Tool usage (Bash, Read, Edit, Agent, etc.)
- Per-tool call counts and estimated token impact
Which project is burning the most tokens. Sort by cost, see session counts.
How many times each tool was called. Highlights if Read or Bash dominates (common waste pattern).
Token split between Opus, Sonnet, Haiku.
Visual bar chart of daily consumption.
Based on your actual usage patterns:
- "86 sessions exceeded 30 turns - use /compact"
- "Read tool is 40% of calls - use Grep to find specific content"
- "840 subagent calls - each duplicates full context"
- "Write calls outnumber Edit 2:1 - Edit sends only the diff"
| ccusage | claude-usage-analyzer | |
|---|---|---|
| Question | "How much did I spend?" | "Why did I spend it? How do I spend less?" |
| Output | Token counts, cost tables | Token sinks, tool attribution, optimization suggestions |
| Accuracy | Known dedup issues (#313, #455) | Last-write-wins dedup on (requestId, uuid) |
| Performance | Node.js, can timeout on large data | Rust, streaming parser |
| Scope | Observability | Optimization |
claude-usage-analyzer is not a replacement for ccusage. Use ccusage for daily/monthly cost tracking. Use claude-usage-analyzer to understand why and what to change.
- Reads all
~/.claude/projects/*/*.jsonlsession files - Deduplicates usage entries using last-write-wins on (requestId, uuid)
- Aggregates by project, tool, model, and day
- Identifies top token sinks with percentage breakdown
- Generates suggestions based on usage patterns
No network access. No API keys. Everything runs locally on your session data.
claude-usage-analyzer shows you where tokens went. cclint shows you what to fix in your config.
cargo install cclint && cclintIt lints your CLAUDE.md, hooks, skills, and commands for token waste. Gives you a health score and specific fixes.
Run claude-usage-analyzer to identify your top token sinks. It shows exactly which tools, projects, and patterns are burning tokens, with specific suggestions like using /compact, switching from Read to Grep, or trimming your CLAUDE.md.
Start with Claude Code cost reduction at the source: run claude-usage-analyzer, look at the "Controllable Token Sinks" section, and act on the top 2-3 suggestions. Common wins include trimming CLAUDE.md, removing unused MCP tools, replacing Read sweeps with targeted Grep, and using /compact earlier in long sessions. Most users cut controllable tokens by 30-60% after one pass.
Usually it's not the model, it's the context. Every turn re-reads your CLAUDE.md, MCP tool definitions, system prompt, and prior conversation. Long sessions, chatty tools (Bash with huge outputs, Read on large files), and repeated subagent calls each multiply that cost. claude-usage-analyzer breaks down exactly which of these is dominating your bill so you can fix the real cause instead of guessing.
ccusage answers "how much did I spend?" with cost tables and token counts. claude-usage-analyzer (formerly ccwhy) answers "why did I spend it?" with tool attribution, anomaly detection, and actionable optimization suggestions. They're complementary tools: use ccusage for tracking, use ccwhy for Claude Code token optimization.
Run claude-usage-analyzer and check the "By Project" section. It ranks every project in ~/.claude/projects/ by total tokens and estimated cost, so you can immediately tell whether one repo is responsible for most of your usage. For a deeper look at a single project, use claude-usage-analyzer sessions to drill into its top sessions.
Yes. claude-usage-analyzer reads session data from ~/.claude/projects/, which is shared across all Claude Code clients: CLI, VS Code, and JetBrains. If you've used Claude Code from any of them, your data is already there and will show up in the report.
The fastest way is brew install SingggggYee/tap/claude-usage-analyzer on macOS. You can also use cargo install claude-usage-analyzer, or download a prebuilt binary from the Releases page.
It parses your local Claude Code session files (JSONL) to break down token usage by project, tool, model, and time. It identifies anomaly sessions, peak/off-peak patterns, and generates optimization suggestions - all offline, no API keys needed.
- Rust 1.75+ (for building)
- Claude Code session data in
~/.claude/projects/
MIT