Analyze Claude Code session data to generate usage reports with token counts, cost estimates, billing block tracking, tool usage stats, and per-project breakdowns.
Inspired by paulrobello/par_cc_usage.
How it works
Claude Code stores session data as JSONL files in:
~/.config/claude/projects/(Linux/macOS primary)~/.claude/projects/(legacy Unix)%USERPROFILE%\.claude\projects\(Windows, default)- Custom path via
CLAUDE_CONFIG_DIRenv var (all platforms)
The script parses these files, extracts assistant message token usage, deduplicates by request ID, and computes:
- Total token usage (input, output, cache)
- Cost estimates using Anthropic pricing
- 5-hour billing block tracking with burn rate
- Per-model breakdown (Opus vs Sonnet)
- Tool usage frequency
- Per-project and per-session stats
- Daily usage trends
Usage
Run the analysis script:
python plugins/cc-usage/skills/cc-usage/scripts/cc_usage.py
Options
| Flag | Description |
|---|---|
-d, --days N |
Number of days to analyze (default: 7) |
-p, --project NAME |
Filter by project name (substring match) |
--no-block |
Hide current billing block section |
--no-projects |
Hide project breakdown |
--no-tools |
Hide tool usage stats |
--no-sessions |
Hide recent sessions list |
-n, --top N |
Number of top items per section (default: 10) |
--json |
Output raw JSON instead of formatted markdown |
Examples
# Last 7 days, full report
python cc_usage.py
# Last 30 days, filter to one project
python cc_usage.py -d 30 -p "my-project"
# Quick overview, no details
python cc_usage.py --no-tools --no-sessions -n 5
# Machine-readable JSON output
python cc_usage.py --json
When to invoke
Run this script for the user when they ask about:
- Their Claude Code usage or costs
- Token consumption or burn rate
- Current billing block status
- Which tools they use most
- Which projects consume the most tokens
- Usage trends over time
Execute via Bash:
python <path-to-script>/cc_usage.py [options]
Then present the markdown output directly to the user -- it renders as formatted tables.
Report sections
- Overview - Total tokens, messages, cost for the period
- Current Billing Block - Active 5-hour block with remaining time, burn rate, projected cost
- Usage by Model - Token and cost split between Opus, Sonnet, etc.
- Tool Usage - Most-used tools with visual bar chart
- Projects - Per-project token and cost breakdown
- Recent Sessions - Most recently active sessions
- Daily Breakdown - Day-by-day token and cost trend with bar chart
Data sources
The script reads Claude Code's native JSONL format. Key fields extracted:
message.usage- token counts (input, output, cache_creation, cache_read)message.model- model identifier for pricing tiermessage.content[].type == "tool_use"- tool call trackingcostUSD- native cost field (used when available, falls back to calculated)requestId- deduplication keytimestamp- for time-based analysis
Pricing
Pricing is defined in a single source of truth: scripts/cc_usage.py (see the MODEL_PRICING table near the top). To update prices, edit that table -- this document intentionally does not duplicate the numbers to avoid drift.
When costUSD is present in the JSONL data, that value takes priority over calculated estimates.