Token Usage

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

1. Grand totals — tokens, estimated cost, session count
2. Model breakdown — cost split by opus/sonnet/haiku with percentages
3. Per-project breakdown — tokens, cost, subagent count per project
4. Period comparison — current vs previous period (with --compare)
5. 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: citedy
• Source: citedy/skills
• License: MIT

Install and usage instructions live in the source repository linked above.