Cross-session token analytics for Claude Code. Parses the JSONL transcript files Claude Code writes to ~/.claude/projects/ and gives you a clear picture of where your tokens — and money — are going.
Running cc-token-stats --detailed produces the full report:
Claude Code — Session Token Analytics
Last 30 days · 1557 sessions · ~/.claude/projects
TOTALS
Input: 318.0k (billed)
Output: 5.5M (billed, 5×)
Cache write: 127.3M
Cache read: 2587.8M (90% discount)
Cache efficiency: 100.0% (cache_read / total_input)
Est. cost: $1861.28 USD
Autocompacts: 14 sessions (18× total)
Entrypoints:
cli 105 sessions ( 6.7%) $ 1634.56
sdk-cli 1452 sessions ( 93.3%) $ 226.72
SESSION OVERHEAD (first-turn input tokens — system prompt + CLAUDE.md + MCP + skills)
Global avg baseline: 28.2k tokens / session
Project Bar Avg baseline
tee-multi-warehouse-stock ████████████████████ 48.4k
existing-comfyballs-brand ██████████████████░░ 45.1k
repo ████████████████░░░░ 40.8k
tee-theme ██████████████░░░░░░ 36.2k
laravel-returns ██████████████░░░░░░ 34.7k
cc-token-stats █████████░░░░░░░░░░░ 23.3k
BY PROJECT
Project Bar Tokens Cost Sess $/sess CacheEff Flags
spor-app ████████████░░░ 511.7M $ 423.89 1199 $ 0.35 100.0% ⚡16x sdk:1194 opus:58%
tee-multi-warehouse-stock ███████████████ 599.2M $ 371.42 15 $ 24.76 100.0% $$$ opus:99%
tee-wp ██████████░░░░░ 430.9M $ 270.06 27 $ 10.00 100.0% $$$ opus:94%
existing-comfyballs-brand ██████░░░░░░░░░ 241.6M $ 167.61 8 $ 20.95 100.0% $$$ opus:100%
laravel-returns ██████░░░░░░░░░ 260.7M $ 155.56 6 $ 25.93 100.0% $$$ opus:100%
hydrogen █████░░░░░░░░░░ 224.7M $ 147.58 10 $ 14.76 100.0% $$$ opus:100%
...
DAILY TREND
Date Bar Sess Cost
2026-03-25 ███████░░░░░░░░░░░░░░░░░░ 32 $ 167.68
2026-03-27 ██████░░░░░░░░░░░░░░░░░░░ 10 $ 154.47
2026-03-30 ██████░░░░░░░░░░░░░░░░░░░ 18 $ 146.86
2026-03-31 ████████████░░░░░░░░░░░░░ 22 $ 292.37
2026-04-01 █████████████████████████ 23 $ 578.35
2026-04-02 ██████████░░░░░░░░░░░░░░░ 27 $ 250.47
2026-04-03 ███░░░░░░░░░░░░░░░░░░░░░░ 322 $ 83.06
COST DISTRIBUTION
< $0.10 █████████████████████████ 1010 sessions $ 6.20
$0.10–0.50 ████████░░░░░░░░░░░░░░░░░ 348 sessions $ 115.38
$0.50–1.00 ██░░░░░░░░░░░░░░░░░░░░░░░ 99 sessions $ 70.28
$1–5 █░░░░░░░░░░░░░░░░░░░░░░░░ 53 sessions $ 119.12
$5–15 ░░░░░░░░░░░░░░░░░░░░░░░░░ 18 sessions $ 153.28
> $15 ░░░░░░░░░░░░░░░░░░░░░░░░░ 29 sessions $ 1397.02
TIME-OF-DAY (session count by hour, local time)
0 1 2 3 4 5 6 7 8 9 10 11
█ █ █ █ █ █ █ █ █ █ █ █
224 135 54 37 43 25 25 294 287 6 9 13
12 13 14 15 16 17 18 19 20 21 22 23
█ █ █ █ █ █ █ █ █ █ █ █
4 35 40 36 2 4 14 8 5 6 51 200
SESSIONS (newest first, top 50)
Date Project Msgs Vel/msg CacheEff Total Cost Qual Flags
2026-04-06 08:21 cc-token-stats 143 88.8k/m 100% 12.7M $ 9.87 B wrt=20 +6sub($5.53) opus+sonnet
2026-04-06 07:43 spor-app 49 43.4k/m 100% 2.1M $ 2.02 A +1sub($0.83)
2026-04-06 07:24 thomasaudunhus 3 19.4k/m 100% 58.2k $ 0.15 S ─
2026-04-06 07:06 tee-wp 47 40.6k/m 100% 1.9M $ 1.24 A +3sub($4.02)
2026-04-06 06:38 empty 20 22.6k/m 100% 452.1k $ 0.25 S ─
... and 1507 more. Use --json for full output.
TOP 10 MOST EXPENSIVE SESSIONS
$142.27 2026-03-31 02:44 spor-app 253.5M tokens 811 msgs qual:B --detail 170db6f7-...
$105.69 2026-04-01 00:32 hydrogen 168.7M tokens 696 msgs qual:B --detail 9bbe782a-...
$101.45 2026-04-01 04:55 tee-multi-warehouse.. 172.7M tokens 609 msgs qual:B --detail ba4c7dd6-...
$ 94.18 2026-03-30 20:26 laravel-returns 168.2M tokens 760 msgs qual:B --detail 9dd75a3e-...
...
AUTOCOMPACT SESSIONS
2026-04-02 23:24 thomasaudunhus 15.9M tokens 216 msgs 1× $11.23 --detail 7803e123-...
2026-04-02 22:32 thomasaudunhus 6.3M tokens 86 msgs 1× $ 6.61 --detail 82ab50ce-...
2026-04-05 22:24 spor-app 1.4M tokens 10 msgs 2× $ 0.29 --detail 625e250b-...
...
TOP FILES BY READ FREQUENCY (across all sessions)
File Reads Sessions
.../.claude/get-shit-done/workflows/plan-phase.md 106 24
.../.claude/get-shit-done/workflows/discuss-phase.md 94 19
.../includes/admin/class-tee-mws-admin-foxway.php 58 5
...
REPETITIVE PATTERNS (sessions with identical prompt prefix, ≥5 occurrences)
Pattern Count Cost Entrypoint Projects
"<local-command-caveat>Caveat: The messages belo..." 50 $ 684.74 cli ecom-db-v2, cc-token-stats, ...
"Analyze test coverage and identify gaps: - Find..." 288 $ 65.11 sdk-cli spor-app
"Analyze this codebase for security vulnerabilit..." 529 $ 57.23 sdk-cli spor-app
Total: 1505 sessions, $993.52
RECOMMENDATIONS
⚠ 558 sessions exceeded 100k tokens
⚠ Autocompact triggered 18× — quality degrades near context limit
⚡ 157 sessions had >150k tokens/msg — likely agent spawns
⚠ 178 large sessions had <30% cache efficiency
✓ Global cache efficiency 100% — excellent
$$$$ tee-wp averages $10.00/session — investigate with: cc-token-stats --project tee-wp
$$$$ laravel-returns averages $25.93/session — investigate with: cc-token-stats --project laravel-returns
⚠ spor-app uses Opus for 58% of cost ($247.40) — est. $98.96 savings by switching to Sonnet
⚠ 5 automated repetitive patterns detected — $226.72 spent on sdk-cli loops
⚠ 43 sessions had subagent cost >50% of parent — $1391.66 in subagent overhead
⚠ 5 files read 50+ times — consider caching or restructuring
⚠ 47 sessions had >15 file reads — redundant context loading
The top-level summary across all sessions in the time window. Shows aggregate input, output, cache write, and cache read token counts with their billing implications. The (billed) and (90% discount) annotations reflect Anthropic's pricing — cache reads are 10x cheaper than regular input. Cache efficiency is cache_read / (input + cache_write + cache_read) — higher is better. Entrypoints breaks down sessions by how they were launched: cli (interactive Claude Code) vs sdk-cli (programmatic/automated usage via the SDK).
Measures the baseline cost of each session before any real work happens. The "first-turn input tokens" is the system prompt, CLAUDE.md instructions, MCP tool definitions, and loaded skills that get sent on the very first API call. Projects with large CLAUDE.md files, many MCP servers, or lots of loaded skills will show higher baselines. Use this to identify projects where configuration bloat is inflating every session's cost.
One row per project, sorted by total cost:
| Column | What it tells you |
|---|---|
| Bar | Visual token volume relative to the highest-volume project — quickly spot outliers |
| Tokens | Total tokens across all types (input + output + cache write + cache read) |
| Cost | Estimated USD based on per-model pricing |
| Sess | Number of sessions in the time window |
| $/sess | Average cost per session — high values (flagged $$$) are worth investigating |
| CacheEff | Cache read as a percentage of total input-side tokens. Green >= 80%, yellow >= 50%, red < 50% |
| Flags | ⚡Nx = autocompact events, $$$ = average session cost > $10, sdk:N = N sessions via SDK, opus:N% = percentage of cost from Opus model |
Bar chart of session count and cost per day. Useful for correlating spend with development activity, spotting billing spikes, or catching runaway automated sessions.
Histogram bucketing all sessions into cost ranges: < $0.10, $0.10–0.50, $0.50–1.00, $1–5, $5–15, > $15. Shows both the number of sessions and total spend per bucket. A healthy distribution has most sessions in the lower buckets. If the > $15 bucket holds a disproportionate amount of total spend, those sessions are candidates for optimization.
Session count by hour in local time, displayed as two rows of 12 hours. Useful for spotting whether background agents, memory observers, or SDK automations are running at unexpected times (e.g., heavy activity at 3 AM when you're not working).
The 50 most recent sessions with per-session metrics:
| Column | What it tells you |
|---|---|
| Msgs | Number of assistant turns in the session |
| Vel/msg | Average tokens per message. Yellow > 50k, red > 150k — very high values indicate agent spawns with large system prompts being injected each turn |
| CacheEff | Per-session cache efficiency |
| Total | Total tokens consumed |
| Cost | Estimated USD for this session |
| Qual | Quality grade S/A/B/C/D/F (see Quality score) |
| Flags | wrt=N file writes, +Nsub($X.XX) sub-agents spawned with their cost, sdk-cli if SDK-launched, autocompact×N, ⚡vel=Xk/m velocity warning, model names if mixed |
The 10 costliest sessions sorted by USD. Each row includes token count, message count, quality grade, and a ready-to-copy --detail command to drill into the session's message-by-message breakdown.
Sessions that hit the context window limit and triggered Claude Code's autocompaction (context summarization). Sorted by total token volume. The ×N column shows how many times compaction fired. Autocompacted sessions typically produce lower-quality output near the end — these are candidates for breaking into smaller sessions with more frequent /clear.
Files most frequently read across all sessions. High read counts on the same file across many sessions may indicate files that should be restructured, cached, or included in CLAUDE.md to avoid redundant tool calls.
Groups sessions that share the same prompt prefix (first 150 characters) and occur 5+ times. Shows total cost and which entrypoint triggered them. Useful for catching SDK automations or recurring scripts that may be running more often than intended, or that could be optimized.
Automated analysis that flags:
| Flag | Meaning |
|---|---|
⚠ N sessions exceeded 100k tokens |
Large sessions that may benefit from being split |
⚠ Autocompact triggered N× |
Quality degrades near context limit — use /clear more often |
⚡ N sessions had >150k tokens/msg |
Likely agent spawns injecting large system prompts each turn |
⚠ N large sessions had <30% cache efficiency |
Poor cache hit rate is inflating costs |
✓ Global cache efficiency N% |
Overall cache health (green = good) |
$$$$ project averages $N/session |
Expensive projects with a ready-to-run drill-down command |
⚠ project uses Opus for N% |
Potential savings by switching to Sonnet, with estimated dollar amount |
⚠ N automated repetitive patterns |
SDK loops that may be costing more than expected |
⚠ N sessions had subagent cost >50% |
Sub-agents dominating session cost — check if spawning is necessary |
⚠ N files read 50+ times |
Redundant file reads across sessions |
⚠ N sessions had >N bash/read calls |
Possible looping or redundant tool usage |
- Per-model pricing — auto-detects Opus, Sonnet, and Haiku usage per session and applies correct rates
- Quality score — grades each session (S/A/B/C/D/F) based on context fill, message count, cache efficiency, output ratio, and autocompact events
- Session overhead analysis — shows average first-turn baseline tokens per project (system prompt + CLAUDE.md + MCP + skills)
- Sub-agent tracking — detects and reports spawned sub-agents with their individual costs
- Daily trend — bar chart of spend over time
- Cost distribution — histogram bucketing sessions by cost
- Time-of-day heatmap — session count by hour to spot unexpected background activity
- Repetition detection — groups sessions by prompt prefix to find recurring automated patterns
- Entrypoint breakdown — separates CLI vs SDK usage
- AI summary — optional one-paragraph summary via
claudeCLI (Haiku) - Detail mode — message-by-message breakdown of any session with tool usage and running context size
- JSON export — full data for custom analysis with
jqor scripts
- Python 3 (stdlib only, no dependencies)
- Claude Code installed and having been run at least once
Download the latest binary for your platform from GitHub Releases:
| Platform | Binary |
|---|---|
| macOS (Apple Silicon + Intel via Rosetta 2) | cc-token-stats-darwin-arm64 |
| Linux x86_64 | cc-token-stats-linux-amd64 |
# macOS Apple Silicon
curl -L https://github.com/thoaud/cc-token-stats/releases/latest/download/cc-token-stats-darwin-arm64 \
-o /usr/local/bin/cc-token-stats
chmod +x /usr/local/bin/cc-token-statsmacOS Gatekeeper: Unsigned binaries may be blocked on first run. Clear the quarantine flag with:
xattr -cr /usr/local/bin/cc-token-stats
./cc-token-stats# Last 30 days, condensed summary
cc-token-stats
# Full detailed output (all sections)
cc-token-stats --detailed
# Narrow the time window
cc-token-stats --days 7
# Filter to a specific project (matches against the path)
cc-token-stats --project my-app
# Filter by entrypoint
cc-token-stats --entrypoint cli
cc-token-stats --entrypoint sdk-cli
# Drill into a single session by ID
cc-token-stats --detail 3465b7d2-9fd5-4ba3-bf63-c6a4612c0764
# Full JSON output for further processing
cc-token-stats --json
cc-token-stats --json | jq '[.[] | select(.estimated_cost_usd > 5)]'
# Skip the AI-generated summary
cc-token-stats --no-summary
# Override context window size for quality scoring
cc-token-stats --context-size 128000
# Override Claude data directory
cc-token-stats --claude-dir /path/to/.claude--detail <session-id> shows a message-by-message breakdown:
# Role In Out CacheR Running Cost Detail
0 user 0 fix the checkout flow
1 assistant 6.2k 1.8k 879.0k 887.0k $0.03 Read(checkout.php), Bash(grep -r …)
2 user 887.0k +3 tool results
3 assistant 1.1k 2.4k 879.0k 1.8M $0.03 Write(checkout.php)
The running total column shows cumulative context growth — useful for spotting where a session ballooned.
Auto-detects model per turn. Default rates (USD per million tokens):
| Input | Output | Cache write | Cache read | |
|---|---|---|---|---|
| Opus | $5.00 | $25.00 | $6.25 | $0.50 |
| Sonnet | $3.00 | $15.00 | $3.75 | $0.30 |
| Haiku | $1.00 | $5.00 | $1.25 | $0.10 |
Each session gets a grade (S through F) based on five weighted factors:
| Factor | Weight | Best | Worst |
|---|---|---|---|
| Context fill | 25% | < 30% of window | > 85% |
| Message count | 25% | <= 20 turns | > 100 turns |
| Cache efficiency | 20% | >= 80% | < 20% |
| Output/input ratio | 15% | >= 5% | < 5% |
| Autocompacts | 15% | 0 | > 2 |
High grades (S/A) indicate focused, efficient sessions. Low grades (D/F) suggest sessions that could benefit from being broken up or restructured.
Claude Code writes a JSONL transcript for every session to ~/.claude/projects/<encoded-path>/<session-id>.jsonl. Each assistant turn includes a usage object with input_tokens, output_tokens, cache_creation_input_tokens, and cache_read_input_tokens, along with the model identifier. The script sums these per session, resolves encoded directory names back to human-readable paths, and renders the output.
MIT