Citedy Token Usage Analyzer
Analyze token consumption patterns and estimate costs from Claude Code session files (~/.claude/projects/).
What It Does
- Parses all JSONL session files to extract token metrics (input, cache creation, cache read, output)
- Groups usage by project and session
- Estimates costs based on Claude model pricing
- Identifies most expensive sessions and subagent usage
- Supports time range filtering (today, week, month, N days, specific date)
- Generates a detailed markdown report
Usage
Run the analyzer with a time range argument:
python3 .claude/skills/token-usage/scripts/analyze.py $ARGUMENTS
Arguments
| Argument | Example | Description |
|---|---|---|
| (empty) | All time | |
today |
today |
Since midnight UTC |
week |
week |
Last 7 days |
month |
month |
Last 30 days |
| N (number) | 3 |
Last N days |
| Date | 2026-04-01 |
Since that date |
| Datetime | 2026-04-01 11:00 |
Since that datetime |
Additional flags
--compare— show current period vs previous period of same length
Example: --compare week shows this week vs last week.
Output
The script prints a summary to stdout and saves a detailed report to:
~/.claude/token-usage-reports/token_report.md
Cost Estimation
Prices are per million tokens, detected automatically per model:
| Model | Input | Cache Create | Cache Read | Output |
|---|---|---|---|---|
| Opus | $15.00 | $18.75 | $1.50 | $75.00 |
| Sonnet | $3.00 | $3.75 | $0.30 | $15.00 |
| Haiku | $0.80 | $1.00 | $0.08 | $4.00 |
The analyzer reads the model field from each assistant message and applies correct pricing automatically.
What the Report Includes
- Grand totals — tokens, estimated cost, session count
- Model breakdown — cost split by opus/sonnet/haiku with percentages
- Per-project breakdown — tokens, cost, subagent count per project
- Period comparison — current vs previous period (with
--compare) - Most costly sessions — ranked by estimated cost with first prompt preview
Tips for Reducing Usage
- Cache read is cheap ($1.50/M vs $15/M for input) — long conversations benefit from cache
- Subagents are expensive — each spawns a fresh context. Use sparingly.
- Review your costliest sessions — often one runaway session costs more than a week of normal work
- Use specific time ranges to track daily/weekly spending patterns
Requirements
- Python 3.8+
- Claude Code (session files in
~/.claude/projects/) - No external dependencies (stdlib only)