acaprino/cc-usage

Claude Code Usage Analyzer

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_DIR env 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

1. Overview - Total tokens, messages, cost for the period
2. Current Billing Block - Active 5-hour block with remaining time, burn rate, projected cost
3. Usage by Model - Token and cost split between Opus, Sonnet, etc.
4. Tool Usage - Most-used tools with visual bar chart
5. Projects - Per-project token and cost breakdown
6. Recent Sessions - Most recently active sessions
7. 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 tier
• message.content[].type == "tool_use" - tool call tracking
• costUSD - native cost field (used when available, falls back to calculated)
• requestId - deduplication key
• timestamp - 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.