claude-usage-calc

name	claude-usage-calc
description	Calculate Claude Code token consumption, message counts, and list-price cost from local JSONL transcript logs. Use when the user asks "how many tokens / prompts / messages did I use", "what's my Claude cost", "usage in last N days", or anything about local Claude Code usage analytics.
allowed-tools	Bash, Read

Claude Code Usage Calculation

Compute token usage, prompt counts, and cost from local Claude Code transcript files.

Where the data lives

• Transcripts: ~/.claude/projects/**/*.jsonl (one file per session, one JSON object per line)
• Each line has timestamp (ISO8601 UTC), type (user | assistant | system), and for assistant lines a message.usage block from the API response
• No transcripts older than ~90d typically exist locally (rotated/cleaned)

CRITICAL: things to get right

1. Each usage block is per-API-call, NOT per-conversation

Verified by inspection: turn 1 has cache_read=11k, turn 146 has cache_read=89k, growing as the cached prefix grows. Summing across turns is correct for billing because each API call is independently charged. Cache reads dominating (often 90%+ of tokens) is expected and normal, not a counting bug.

2. DEDUPE BY message.id — THIS IS THE BIGGEST FOOTGUN

Claude Code logs the same assistant message multiple times across parent chains and sidechain entries. Without dedup, totals are inflated ~2.4×. Always keep a seen set of message.id and skip duplicates. A real measurement showed 794k raw assistant entries collapsing to 376k unique turns.

3. "Real human prompts" ≠ all type:user entries

The harness logs tool_result continuations as type:user. To count actual prompts the human sent, filter type:user entries AND exclude any whose message.content is a list containing a block with type=="tool_result". In a real run: 564,909 raw user entries → 53,406 actual human prompts.

4. Filter by timestamp, not file mtime

File mtime is unreliable (a session touched today may include messages from weeks ago). Parse timestamp per line and bucket by (now - t).days.

5. List price ≠ what the user actually pays

ALWAYS state this explicitly in the report. If the user is on Max / Pro / committed-use / enterprise, real billing is dramatically lower. Tell them the authoritative number is at console.anthropic.com or claude.ai billing.

6. Pricing per million tokens (USD, list price)

Family	input	output	cache_create	cache_read
opus	15.00	75.00	18.75	1.50
sonnet	3.00	15.00	3.75	0.30
haiku	0.80	4.00	1.00	0.08

Detect family from message.model substring (opus / sonnet / haiku). Default unknown to sonnet.

What NOT to do

• ❌ Do not sum raw assistant entries without deduping by message.id
• ❌ Do not count all type:user entries as "prompts" (most are tool_results)
• ❌ Do not filter by file mtime instead of per-line timestamp
• ❌ Do not present list-price cost as "what you paid" — always caveat it
• ❌ Do not exclude cache_read from totals "because it looks too big" — it IS billed (at 0.1× input)
• ❌ Do not assume usage is cumulative across the conversation — it is per-API-call
• ❌ Do not write throwaway scripts in the repo or home dir — use scripts/ (gitignored) if needed

What TO do

• ✅ Stream all JSONLs through one Python pass via find ... -print0 | xargs -0 cat | python3 -c '...'
• ✅ Dedupe by message.id with a seen set
• ✅ Bucket by age: 0-30d, 30-60d, 60-90d for trend questions
• ✅ Break out by model family (opus / sonnet / haiku) — Opus typically dominates cost
• ✅ Report all four token buckets separately: input, output, cache_create, cache_read
• ✅ Always show: real human prompts, unique assistant turns, total tokens, list-price cost
• ✅ Caveat that list price ≠ real bill
• ✅ Point user to console.anthropic.com or claude.ai billing for ground truth

Reference script

Run this to compute last-30d usage. Adjust the day window as needed.

find ~/.claude/projects -name "*.jsonl" -print0 2>/dev/null | xargs -0 cat 2>/dev/null | python3 -c "
import sys, json
from datetime import datetime, timezone
now = datetime.now(timezone.utc)
WINDOW_DAYS = 30

PRICES = {
  'opus':   {'in':15.00,'out':75.00,'cc':18.75,'cr':1.50},
  'sonnet': {'in': 3.00,'out':15.00,'cc': 3.75,'cr':0.30},
  'haiku':  {'in': 0.80,'out': 4.00,'cc': 1.00,'cr':0.08},
}
def fam(m):
    if not m: return 'sonnet'
    m = m.lower()
    if 'opus' in m: return 'opus'
    if 'haiku' in m: return 'haiku'
    return 'sonnet'

seen = set()
agg = {}
real_user_msgs = 0
dup_skipped = 0

for line in sys.stdin:
    try:
        d = json.loads(line)
        ts = d.get('timestamp')
        if not ts: continue
        t = datetime.fromisoformat(ts.replace('Z','+00:00'))
        if (now - t).days >= WINDOW_DAYS: continue

        if d.get('type') == 'user':
            msg = d.get('message',{})
            c = msg.get('content') if isinstance(msg,dict) else None
            tool_result = isinstance(c,list) and any(isinstance(x,dict) and x.get('type')=='tool_result' for x in c)
            if not tool_result:
                real_user_msgs += 1
            continue

        if d.get('type') != 'assistant': continue
        msg = d.get('message') if isinstance(d.get('message'),dict) else None
        if not msg: continue
        mid = msg.get('id')
        if mid:
            if mid in seen:
                dup_skipped += 1
                continue
            seen.add(mid)
        u = msg.get('usage') or {}
        f = fam(msg.get('model'))
        a = agg.setdefault(f, {'in':0,'out':0,'cc':0,'cr':0,'turns':0})
        a['in']  += u.get('input_tokens',0) or 0
        a['out'] += u.get('output_tokens',0) or 0
        a['cc']  += u.get('cache_creation_input_tokens',0) or 0
        a['cr']  += u.get('cache_read_input_tokens',0) or 0
        a['turns'] += 1
    except: pass

grand_cost = 0.0
grand_tok  = 0
print(f'{\"model\":<8} {\"turns\":>9} {\"in\":>14} {\"out\":>14} {\"cc\":>16} {\"cr\":>16}   {\"cost\":>11}')
for f,a in sorted(agg.items()):
    p = PRICES[f]
    cost = (a['in']*p['in']+a['out']*p['out']+a['cc']*p['cc']+a['cr']*p['cr'])/1_000_000
    grand_cost += cost
    grand_tok += a['in']+a['out']+a['cc']+a['cr']
    print(f\"{f:<8} {a['turns']:>9,} {a['in']:>14,} {a['out']:>14,} {a['cc']:>16,} {a['cr']:>16,}   \${cost:>10,.2f}\")
print()
print(f'real human prompts:    {real_user_msgs:,}')
print(f'unique assistant turns: {sum(a[\"turns\"] for a in agg.values()):,}  (deduped {dup_skipped:,} duplicates)')
print(f'TOTAL tokens:           {grand_tok:,}')
print(f'TOTAL cost (LIST price): \${grand_cost:,.2f}')
print()
print('NOTE: list price; real bill is lower if on Max/Pro/committed-use.')
print('Authoritative usage: console.anthropic.com or claude.ai billing.')
"

Reporting format

Always report (in this order):

1. Real human prompts sent in window
2. Unique assistant API calls (with dedup count noted)
3. Per-model breakdown table (turns / input / output / cache_create / cache_read / cost)
4. TOTAL tokens and TOTAL list-price cost
5. Caveat: list price ≠ real bill, point to console for ground truth
6. If asked about trends, also bucket 30-60d and 60-90d and explain growth drivers (cache_read inflation from longer sessions / parallel agents is normal)