tokenxray 0.2.0

See where your AI coding tokens actually go. Analyze Claude Code session costs, find token bombs, and track spending.

TokenXRay

See where your AI coding tokens actually go.

I spent $104 in a single Claude Code session. Then I audited all 514 of mine and found that 9% of sessions burned 92% of the money — $11,600 out of $12,600 total. The culprit: context that grows quadratically, cache creation fees nobody mentions, and tool results that ride in context forever.

Install

pip install tokenxray
tokenxray --install-hook --confirm   # one-time setup, then forget about it

Zero dependencies. Pure Python stdlib. Python 3.9+.

How It Works

TokenXRay has two layers: hooks that run automatically inside Claude Code, and a CLI you run when you want to review your spending.

Daily: Hooks (automatic, zero effort)

After --install-hook, every Claude Code session gets two hooks that run silently in the background:

1. Cost hook — tracks your running cost after every tool use. Shows a status line every 10 turns. Alerts when you cross $10/$25/$50/$100. At 80 turns or $30, auto-saves your session state to .claude/checkpoint.md.
2. Resume hook — when you start a new session, detects the checkpoint and restores context automatically. One-shot: fires once, then gets out of the way.

Your daily workflow:

Open Claude Code → checkpoint detected? context restored automatically
       ↓
Work normally → cost hook tracks silently in background
       ↓
Hit 80 turns or $30 → checkpoint auto-saved
       ↓
You decide: keep going or start fresh (checkpoint is saved either way)
       ↓
Start fresh → next session picks up where you left off

You never run tokenxray during a session. The hooks handle it.

[TokenXRay] Opus — turn 40, $12.50 total, ~$0.31/turn, ctx 85K
[TokenXRay] Consider splitting this session! (80 turns, $31.20, ctx 120K)
[TokenXRay] Auto-checkpoint saved to .claude/checkpoint.md

Weekly: CLI (manual review)

Run these when you want to understand your spending patterns and change habits:

tokenxray                  # Overview — where your money goes
tokenxray --diagnose       # Specific recommendations
tokenxray --session <id>   # Deep dive into one session
tokenxray --dashboard      # Interactive HTML charts
tokenxray --projects       # Cost by project

TokenXRay - Session Overview
----------------------------------------------------------------------
  514 sessions    43,000+ total turns    $12,600+ total cost

  Segment Breakdown:
    1-10 turns:  329 sessions  avg  $0.19   total    $62   ░░░░░░░░░░  0%
         11-30:   76 sessions  avg  $4.01   total   $305   ░░░░░░░░░░  2%
        31-100:   61 sessions  avg $11.05   total   $674   █░░░░░░░░░  5%
          100+:   48 sessions  avg   $241   total $11,600  ████████░░ 92%

The retrospective analysis is the most valuable part. After a few --diagnose runs, you start naturally scoping sessions better — "I'll do the refactor, then start fresh for tests." That's where the real savings come from.

Configuration

Customize hook thresholds in ~/.tokenxray/config.json:

{
    "split_turns": 80,
    "split_cost": 30,
    "alert_thresholds": [10, 25, 50, 100, 200, 500],
    "status_interval": 10
}

Supported Tools

Tool	Source	Notes
Claude Code	~/.claude/projects/**/*.jsonl	Full token breakdown: input, output, cache read, cache create
Gemini CLI	~/.gemini/tmp/*/chats/session-*.json	Input, output, cached, thinking tokens
GitHub Copilot	VS Code workspace storage	Estimated from message lengths (token events are ephemeral)

tokenxray --source claude    # Claude only
tokenxray --source gemini    # Gemini only
tokenxray --source copilot   # Copilot only
tokenxray --source all       # Everything (default)

Your data stays local. TokenXRay reads files on your machine. Nothing is sent anywhere.

Additional Flags

Flag	Description
--top N	Show top N sessions (default: 15)
--path <dir>	Custom path to session logs directory
--no-color	Disable colored output
--baseline / --compare	Save baseline, compare after changing habits
--export csv	Export sessions to CSV
--checkpoint	Manually extract session state

The Full Story

Read the detailed analysis: I Spent $104 in a Single AI Coding Session. Then I Audited All 514 of Mine.

License

MIT