SuperAPI AI Directory

cc-usage

General & other

View repository

Updated 10-16 05:45

About this skill

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.