Cc Usage

Claude Code Usage & Cost Analysis

Analyzes the current machine's Claude Code usage from the local transcript store at ~/.claude/projects//.jsonl. Each assistant message carries a usage block; this skill sums it across every project and prices it as if run on the pay-as-you-go API. It reports on whoever is running it — there is no per-user attribution beyond the local transcripts.

When to use

• "compute my token usage", "how long is my history", "total input/output tokens"
• "how much would I have paid without a subscription", "what's my API-equivalent cost"
• "max daily / weekly consumption", "top days", "weekly spend min/max/median/mean"
• "what if I ran everything on Fable / Opus / Sonnet / Haiku"

How to run

Everything is in scripts/usage.py (Python 3 stdlib only, no dependencies):

python3 "$CLAUDE_SKILL_DIR/scripts/usage.py" [flags]

If $CLAUDE_SKILL_DIR is unset, use the skill's own directory (e.g. ~/.claude/skills/cc-usage/scripts/usage.py).

Common invocations:

• Totals + all-time summary (span, input/output/cache tokens, $): no flags
• Max daily consumption: --by day --top 10 (add --rank cost to rank by $)
• Per-week tokens + $: --by week
• Clean weekly stats: --by week --full-weeks-only --stats
• Reprice everything at one model: add --model fable (or opus/sonnet/haiku)

Accounting rules (already encoded in the script — do not re-derive)

• Dedup by the record uuid (the canonical per-record key). Consider every

record that carries a usage dict; skip anything else. Subagent/sidechain sessions live in separate files but each message has its own uuid, so they are additive and counted once. Do NOT dedupe by (message.id, requestId) — that collapses genuinely-distinct messages (null/repeated message ids) and undercounts by ~2×.

• "Total tokens" = input + output + cache_read + cache_creation. This is

dominated by cache traffic; the raw input+output is far smaller (Claude Code re-reads the cached context every turn). Always say so when reporting totals.

• Cost uses the actual per-message message.model mix by default. Rates per

1M tokens: Opus $5/$25, Sonnet $3/$15, Haiku $1/$5, Fable $10/$50. Unknown models fall back to the Opus tier. Update RATES in the script if list prices change.

• Cache pricing off the base input rate: read ×0.1, 5-min write ×1.25,

1-hour write ×2.0. Writes are split via usage.cache_creation.ephemeral_{1h,5m}_input_tokens; if unsplit, cache_creation_input_tokens is treated as 5-min.

• Weeks are ISO weeks (date.isocalendar()). --full-weeks-only drops the

first and last ISO week of the covered span (their coverage is clipped by the data boundaries) — a low-usage middle week is NOT partial and is kept. Use this before quoting weekly statistics, since the boundary weeks skew the distribution.

Reporting guidance

• --model gives a strict upper bound — you would never realistically run

bulk Haiku-tier work on the top model. Say so when repricing at Fable.

• The distribution is right-skewed (ramp-up weeks vs steady-state): median ≪ mean.

Call that out rather than reporting mean alone.

Files

• scripts/usage.py — the whole analysis; stdlib-only, safe to run read-only.

Source & license

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

• Author: liberzon
• Source: liberzon/cc-usage
• License: MIT

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