usage-details

Cache Usage Details

Analyze cache efficiency and token spend for Claude Code sessions.

Arguments

Parse $ARGUMENTS to determine mode:

• No arguments: analyze current session (most recently modified JSONL under ~/.claude/projects/)
• Session ID prefix (e.g., be607d): find and analyze matching session
• --since YYYYMMDD: show multi-session overview since that date
• --list: show all sessions sorted by cost (highest first)

How to execute

Use the Bash tool to run Python one-liners that parse JSONL session files. All scripts use only Python stdlib (json, sys, os, glob, collections). Output results as formatted markdown tables.

Step 1: Find the session

python3 -c "
import os, glob

args = '''$ARGUMENTS'''.strip()

# Find all session files
files = glob.glob(os.path.expanduser('~/.claude/projects/*/*.jsonl'))
if not files:
    print('No session files found.')
    exit(0)

if args.startswith('--since') or args == '--list':
    # Multi-session mode — print all paths
    for f in sorted(files, key=lambda x: os.path.getmtime(x), reverse=True):
        print(f)
elif args:
    # Find by ID prefix
    matches = [f for f in files if args in os.path.basename(f)]
    if matches:
        print(matches[0])
    else:
        print(f'No session matching \"{args}\" found.')
else:
    # Current session — most recently modified
    print(max(files, key=os.path.getmtime))
"

Step 2: For single session — run all 4 analyses

Run 2a (Hourly Timeline), 2b (Cliff Detection), 2c (Trigger Attribution), and 2d (Subagent Sessions). Step 2d is skipped automatically if no Agent tool_use blocks are found. Replace SESSION_PATH_HERE with the actual path from Step 1 in each script.

2a. Hourly Cache Timeline

python3 << 'PYEOF'
import sys, json, os
from collections import defaultdict

transcript = "SESSION_PATH_HERE"  # Replace with actual path from step 1

calls = []
with open(transcript) as f:
    for line in f:
        try: m = json.loads(line.strip())
        except: continue
        if m.get('type') != 'assistant': continue
        usage = m.get('message', {}).get('usage', {})
        if not usage or 'output_tokens' not in usage: continue
        cw = usage.get('cache_creation_input_tokens', 0)
        cr = usage.get('cache_read_input_tokens', 0)
        inp = usage.get('input_tokens', 0)
        out = usage.get('output_tokens', 0)
        ts = m.get('timestamp', '')
        calls.append({'ts': ts, 'cw': cw, 'cr': cr, 'inp': inp, 'out': out})

if not calls:
    print("No API calls with usage data found.")
    sys.exit(0)

# Group by hour
hourly = defaultdict(lambda: {'cw': 0, 'cr': 0, 'out': 0, 'calls': 0, 'cost': 0})
for c in calls:
    hour = c['ts'][:13]
    hourly[hour]['cw'] += c['cw']
    hourly[hour]['cr'] += c['cr']
    hourly[hour]['out'] += c['output'] if 'output' in c else c['out']
    hourly[hour]['calls'] += 1
    hourly[hour]['cost'] += c['inp']*5/1e6 + c['out']*25/1e6 + c['cw']*6.25/1e6 + c['cr']*0.50/1e6

print("## Hourly Cache Timeline")
print()
print(f"| Hour | Calls | CacheW | CacheR | Ratio | Output | Cost |")
print(f"|------|-------|--------|--------|-------|--------|------|")
for hour in sorted(hourly.keys()):
    h = hourly[hour]
    ratio = f"{h['cr']/h['cw']:.0f}:1" if h['cw'] > 0 else "N/A"
    cliff = " CLIFF" if h['cw'] > 0 and h['cr']/h['cw'] < 1 else ""
    print(f"| {hour[5:]} | {h['calls']} | {h['cw']/1e6:.1f}M | {h['cr']/1e6:.1f}M | {ratio} | {h['out']/1e3:.1f}K | ${h['cost']:.2f}{cliff} |")

# Totals
total_cw = sum(h['cw'] for h in hourly.values())
total_cr = sum(h['cr'] for h in hourly.values())
total_out = sum(h['out'] for h in hourly.values())
total_cost = sum(h['cost'] for h in hourly.values())
total_calls = sum(h['calls'] for h in hourly.values())
ratio = f"{total_cr/total_cw:.0f}:1" if total_cw > 0 else "N/A"
print(f"| **TOTAL** | **{total_calls}** | **{total_cw/1e6:.1f}M** | **{total_cr/1e6:.1f}M** | **{ratio}** | **{total_out/1e3:.1f}K** | **${total_cost:.2f}** |")
PYEOF