Metadata-Version: 2.4
Name: tokenxray
Version: 0.3.26
Summary: Live cost alerts, hard-stop ceiling, and session analysis for Claude Code. The spending guard Claude Code doesn't ship with.
Author: Md Niajul Hasan
License-Expression: MIT
Project-URL: Homepage, https://github.com/Crack525/tokenxray
Project-URL: Repository, https://github.com/Crack525/tokenxray
Project-URL: Issues, https://github.com/Crack525/tokenxray/issues
Keywords: claude,tokens,cost,llm,ai,claude-code,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="assets/logo.svg" alt="TokenXRay" width="360"/>
</p>

<p align="center">
  <a href="https://pypi.org/project/tokenxray/"><img src="https://img.shields.io/pypi/v/tokenxray" alt="PyPI"></a>
  <a href="https://pypistats.org/packages/tokenxray"><img src="https://img.shields.io/pypi/dm/tokenxray" alt="Downloads"></a>
  <a href="https://pypi.org/project/tokenxray/"><img src="https://img.shields.io/pypi/pyversions/tokenxray" alt="Python"></a>
  <a href="https://github.com/Crack525/tokenxray/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/tokenxray" alt="License"></a>
</p>

<p align="center"><strong>Claude Code has no spending ceiling. TokenXRay adds one.</strong></p>

I spent $104 in a single Claude Code session. Then I audited all 686 of mine and found that **10% of sessions burned 89% of the money** — $12,560 out of $14,000+ total. The culprit: context that grows quadratically, cache creation fees nobody mentions, and tool results that ride in context forever.

<p align="center">
  <img src="blog/tokenxray-explained.png" alt="TokenXRay — The Problem and Solution" width="800">
</p>

<table>
  <tr>
    <td align="center" width="50%">
      <img src="demo/demo.gif" alt="tokenxray CLI — overview, session drill-down, diagnose"/><br/>
      <sub><b>CLI</b> — overview · session drill-down · diagnose</sub>
    </td>
    <td align="center" width="50%">
      <video width="100%" autoplay loop muted playsinline>
        <source src="demo/demo-session.mp4" type="video/mp4">
        <img src="demo/demo-session.gif" alt="TokenXRay status line — live hints in Claude Code"/>
      </video>
      <sub><b>Status line</b> — live cost + hints in every Claude Code session</sub>
    </td>
  </tr>
</table>

## Install

```bash
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 three layers: a **status line** always visible at the bottom of Claude Code, **hooks** that run automatically after every tool call, and a **CLI** you run when you want to review spending patterns.

### The ceiling: hard-stop mode

No other Claude Code tool will forcibly halt a runaway session. TokenXRay can. When `hard_stop` is enabled in config, the hook exits with code 2 after every tool call once a ceiling is crossed — Claude Code cannot continue until you start a fresh session.

Enable it once:

```json
{"hard_stop": true, "hard_stop_turns": 120, "hard_stop_cost": 10}
```

When the ceiling hits, every tool call fires this in the conversation:

```
[TokenXRay] HARD STOP — cost limit ($10.43/$10) reached. Session blocked.
Please wrap up and start a fresh session.
Checkpoint was auto-saved earlier. Disable with: hard_stop=false in ~/.tokenxray/config.json
```

Claude Code stops. The session cost stops. Off by default — enable only if you want a hard ceiling. The advisory split warning fires regardless.

### Always-on: live alerting

The hook fires after every tool call. When you cross a cost threshold, you see it immediately in the conversation — no checking required:

```
[TokenXRay] $3.14 spent (crossed $3) — Sonnet 4.6, 28 turns, ctx 42K, ~$0.11/turn
```

Default thresholds: `$1, $3, $5, $10, $25, $50`. Fully configurable. Alerts fire once per threshold per session and don't repeat.

### Always-on: Status Line

After `--install-hook`, a persistent status line appears at the bottom of every Claude Code session showing live session health:

```
Opus │ $5.60 │ ▸▸ │ T42 │ ~$0.13/t │ ctx 38% │ ~43 left │ 27m
```

| Field | Meaning |
|-------|---------|
| `Opus` | Current model |
| `$5.60` | Total session cost (color-coded: green < $1, yellow < $5, red > $15) |
| `▸▸` | Spend velocity — more arrows = burning faster per turn |
| `T42` | Turn count |
| `~$0.13/t` | Average cost per turn |
| `ctx 38%` | Context window usage (color-coded: green < 50%, yellow < 75%, red > 90%) |
| `~43 left` | Estimated turns remaining before context fills |
| `27m` | Session duration |

**Actionable hints** — when a trigger fires, the status line switches from full metrics to a focused action line:

```
Opus │ $5.60 │ ctx 87% │ 🔥 ctx 87% — split now or lose context
```

Hints are prioritized — only the highest-priority action shows:

| Priority | Trigger | Hint |
|----------|---------|------|
| P1 | Rate limit < 3 requests left | `⚠ N req left — pause or hit rate limit` |
| P2 | Context > 85% | `🔥 ctx X% — run: tokenxray --checkpoint · new session` |
| P3 | Context > 60% | `⚠ ctx X% — new session soon · saves ~60% tokens` |
| P4 | Opus + cost > $3 | `→ /model sonnet — same task, 5x cheaper` |
| P5 | 80+ turns + cost > $2 | `→ run: tokenxray --checkpoint · new session · say: read checkpoint.md.loaded` |

Disable hints (keep metrics): set `"statusline_hints": false` in `~/.tokenxray/config.json`.

### Daily: Hooks (automatic, zero effort)

After `--install-hook`, every Claude Code session gets three 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 $1/$3/$5/$10/$25/$50. At 60 turns or $5, auto-saves your session state to `.claude/checkpoint.md`. If you're on Opus, nudges you once to consider switching to Sonnet (5x cheaper for most tasks).
2. **Resume hook** — when you start a new session, detects the checkpoint and prints last session stats + the checkpoint path. **Claude does not read the checkpoint automatically** — tell it to: *"read .claude/checkpoint.md.loaded"*. One-shot: fires once per session, then gets out of the way.
3. **Subagent hook** — fires before each `Agent` tool call. Full warning on first call per session, brief reminder every 5 calls. Agents spawn new context windows at full cost — this nudges you to consider whether delegation is worth it.

Your daily workflow:
```
Open Claude Code → status line shows live metrics at bottom
       ↓
Checkpoint detected? Stats shown in conversation
       ↓
Tell Claude: "read .claude/checkpoint.md.loaded" → context restored
       ↓
Work normally → cost hook + status line track silently
       ↓
Hit 60 turns or $5 → checkpoint auto-saved
       ↓
Status line hint fires? Take the action or keep going
       ↓
Start fresh → next session picks up where you left off
```

You never run `tokenxray` during a session. The hooks and status line handle it.

```
[TokenXRay] Opus — turn 40, $12.50 total, ~$0.31/turn, ctx 85K
[TokenXRay] You're on Opus ($15/MTok input) — Sonnet costs 5x less and handles most coding tasks well.
[TokenXRay] Consider switching: /model claude-sonnet-4-6
[TokenXRay] Consider splitting this session! (60 turns, $5.20, ctx 90K)
[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:

```bash
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 --mcp            # MCP tool audit — find dead-weight servers
```

```
TokenXRay - Session Overview
----------------------------------------------------------------------
  686 sessions    53,952 total turns    $14,044 total cost

  Segment Breakdown:
    1-10 turns:  388 sessions  avg  $0.19   total    $74   ░░░░░░░░░░  <1%
         11-30:  110 sessions  avg  $3.18   total   $350   ░░░░░░░░░░   2%
        31-100:  117 sessions  avg  $9.08   total $1,062   █░░░░░░░░░   8%
          100+:   71 sessions  avg   $177   total $12,560  ████████░░  89%
```

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`:

```json
{
    "split_turns": 60,
    "split_cost": 5,
    "alert_thresholds": [1, 3, 5, 10, 25, 50],
    "status_interval": 10,
    "debug_log": false,
    "hard_stop": false,
    "hard_stop_turns": 120,
    "hard_stop_cost": 50,
    "opus_nudge": true,
    "opus_nudge_turn": 20,
    "opus_nudge_cost": 5.0,
    "subagent_warn": true,
    "subagent_warn_interval": 5,
    "statusline_hints": true
}
```

## Debugging Hooks

By default, hooks only print user-facing messages in conversation. If you need deeper diagnostics, enable internal hook logging:

```json
{"debug_log": true}
```

This writes hook events to `~/.tokenxray/debug.log` (cost/resume/subagent hooks). Useful when a warning seems missing and you want to verify whether the hook fired, skipped, or hit an exception-safe path.

```bash
tail -f ~/.tokenxray/debug.log
```

Set `"debug_log": false` when done.

## 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) |

```bash
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 |
| `--mcp` | MCP tool audit — dead-weight servers, unused tools, schema cost estimate |
| `--mcp --enumerate-tools` | Spawn each configured MCP server and get exact tool counts |

## MCP Tool Audit

Every MCP server you configure globally loads its full tool schema into Claude's context on every session start — roughly **185 tokens per tool**. At 84 tools across a few servers, that's ~15K tokens per session, silently added even when you never call a single MCP tool.

```bash
tokenxray --mcp                   # Audit from call history
tokenxray --mcp --enumerate-tools # Also spawn servers to get exact tool counts
```

Output shows per-server call rates, never-called tools, and a dead-weight estimate: sessions that loaded schemas but called zero MCP tools. The fix is usually moving from global `~/.claude.json` config to project-level `.mcp.json` so servers only load where you actually use them.

## The Full Story

Read the detailed analysis: [I Spent $104 in a Single AI Coding Session. Then I Found Where $8,000 Disappeared.](blog/i-spent-104-dollars-in-one-ai-session.md)

## License

MIT
