rlespinasse/claude-code-usage-report

Claude Code Usage Report

Analyze Claude Code token consumption and estimate costs from session JSONL files stored locally in ~/.claude/projects/.

When to Use

• User wants to know how many tokens they have consumed
• User asks for a cost estimate of their Claude Code usage
• Comparing API pricing vs subscription plan value
• Analyzing usage patterns across projects or time periods

Data Source

Session data is stored as JSONL files in ~/.claude/projects/<project-id>/:

• Main session files: <project-dir>/*.jsonl
• Subagent session files: <project-dir>/*/subagents/*.jsonl

Each line is a JSON object. Token usage is at message.usage:

| Field | Description | | --- | --- | | input_tokens | Direct input tokens | | output_tokens | Model output tokens | | cache_read_input_tokens | Tokens read from prompt cache | | cache_creation_input_tokens | Tokens written to prompt cache (5m or 1h TTL) |

Model identification is at message.model (contains opus, sonnet, or haiku). Timestamps are at timestamp (ISO 8601 format).

Pricing

All pricing data (model token costs and subscription plans) is stored in scripts/pricing.json — the single source of truth used by the script. The file includes an updated date field so the user can see when prices were last verified.

Prompt caching has two write tiers: 5-minute (1.25x base input) and 1-hour (2x base input). Cache reads cost 0.1x base input. The script uses the 5-minute cache write price for cost estimation because Claude Code uses ephemeral caching.

If the user asks to update pricing:

1. Run python3 <skill-path>/scripts/usage_report.py --update-pricing to display the current pricing.json values and update the checked date
2. Fetch https://docs.anthropic.com/en/docs/about-claude/pricing using your web tools to get the latest prices
3. Compare fetched prices with pricing.json values
4. Edit pricing.json with any changed values

The report displays the pricing data date so the user knows how current the prices are.

Report Process

Step 1: Determine Scope

Parse the user's request to determine:

• Date range: "since Feb 18", "last month", "all time", "this week"
• Project filter: specific project, current project, or all projects

If the user does not specify a scope, ask them to clarify. Default to "all projects" if only a date range is given.

Step 2: Collect Data

Run the bundled script at scripts/usage_report.py to scan and aggregate session data. Resolve the script path relative to the skill installation directory.

python3 <skill-path>/scripts/usage_report.py \
  [--start-date YYYY-MM-DD] \
  [--end-date YYYY-MM-DD] \
  [--project PROJECT_NAME] \
  [--output PATH] \
  [--update-pricing]

| Argument | Description | Default | | --- | --- | --- | | --start-date | Include only data on or after this date | No filter | | --end-date | Include only data on or before this date | No filter | | --project | Project directory name or substring | All projects | | --output | Report output file path | ~/claude-code-usage-report.txt | | --update-pricing | Fetch pricing page and guide update of pricing.json | — |

The script outputs the formatted report to stdout and saves it to the output file. It uses only Python stdlib (no dependencies to install).

The report always includes a Plan ROI Comparison section showing savings for all plans (Pro, Max 5x, Max 20x) against API-equivalent cost.

Step 3: Present the Report

The script produces a formatted report with these sections:

1. Global Summary — active projects, session counts, total tokens, API equivalent cost
2. Plan ROI Comparison — savings for Pro, Max 5x, and Max 20x plans
3. Model Breakdown — per-model token counts and costs with a TOTAL row
4. Cost Breakdown by Type — input/output/cache cost split per model
5. Daily Usage — tokens and cost per active day
6. Per-Project Breakdown — sorted by cost descending with per-model detail

Present the script output to the user. The report is also saved automatically to the --output path (default ~/claude-code-usage-report.txt). Inform the user of the saved file path.

Step 4: Highlight Key Insights

After the full report, add a brief summary highlighting:

• Top 5 projects by cost
• Peak usage day
• ROI vs API pricing (if plan context is known)
• Any notable patterns (e.g., one project dominating usage)

Display Guidelines

• Format large numbers with commas (e.g., 1,234,567)
• Right-align numeric columns
• Use $X.XX format for costs
• Clean project names for readability (strip path prefixes)
• Sort projects by cost descending
• Show percentages for savings and cost distribution

Edge Cases

• Missing timestamps: Skip messages without timestamps for filtered reports
• Unknown models: Group under "other" using Sonnet pricing as fallback
• Empty sessions: Skip projects with zero tokens in the filtered period
• Old session cleanup: Claude Code may prune old session files — mention this if the user asks about older periods and data seems incomplete
• Multiple plans: If the user switched plans during the period, ask for the switch date and compute each period separately

Anti-patterns to Avoid

| Anti-pattern | Better alternative | | --- | --- | | Generating a script from scratch | Use the bundled scripts/usage_report.py | | Making per-file tool calls | The bundled script scans everything | | Hardcoding prices in the skill | Prices live in scripts/pricing.json | | Ignoring subagent files | Script includes */subagents/*.jsonl | | Showing raw directory names | Script cleans up to readable project names | | Omitting cache tokens | Script shows all four token types | | Guessing the date range | Ask the user if ambiguous |