@yixi/token-doctor

tokenlens

Local Claude Code spend analyzer. Free standalone tool.

tokenlens reads your local Claude Code session transcripts and tells you where your tokens went. No signup. No cloud upload. No telemetry. Runs entirely on your machine against the JSONL files Claude Code already writes to ~/.claude/projects/.

It surfaces:

• Per-session cost — input / cache-read / cache-write / output, broken down per model
• Category breakdown — tool-use turns vs. chat-only turns vs. thinking-only turns
• Cache hit rate — and how much money a low cache hit rate is costing you
• Chat-only ratio — if you're spending 50% of your turns talking instead of doing, that's flagged
• Output-to-input ratio — verbose responses cost real money; flagged if abnormal
• Repeated-tool streaks — five Read calls in a row usually means a missed parallel batch

Install

# global
npm install -g @yixi/token-doctor

# or without install
npx @yixi/token-doctor

Use

# Most recent session
tokenlens

# Most recent 3 sessions
tokenlens --recent 3

# Filter by project name substring
tokenlens --project my-app

# All sessions everywhere
tokenlens --all

# A specific session file
tokenlens ~/.claude/projects/-root-money/00782c0b-*.jsonl

# Machine-readable JSON
tokenlens --json > report.json

# Exit code only, no output
tokenlens --quiet

Sample output

TOKENLENS REPORT
====================

00782c0b  1h 12m  claude-opus-4-7
  283 assistant turns  — cost $188.67
  tool-use: 177, other: 60, chat-only: 46
  [LOW] Detected 4 streaks of ≥5 consecutive same-tool calls
    Evidence: often a sign of one-at-a-time tool use where parallel calls would have worked
    Fix: See CLAUDE.md section on "parallel tool calls when independent" — many sequential reads/greps can usually batch.

Pricing snapshot: May 2026. Cross-check with https://www.anthropic.com/pricing

Exit codes

Code	Meaning
0	No HIGH waste signals
1	HIGH waste signals present (use this for shell scripting / CI gates)

Pricing assumptions

tokenlens uses pricing from May 2026, per Anthropic's public pricing page:

Model	Input	Cache read	Cache write	Output	(per 1M tokens)
Opus 4.7	$15.00	$1.50	$18.75	$75.00
Sonnet 4.6	$3.00	$0.30	$3.75	$15.00
Haiku 4.5	$1.00	$0.10	$1.25	$5.00

Update src/pricing.js if Anthropic changes prices. Cross-check totals against your actual Anthropic console billing — tokenlens is an estimate, not an invoice.

Privacy

tokenlens runs entirely on your machine:

• It only reads ~/.claude/projects/ (or wherever you point it)
• It never opens a network socket
• It never reads message content — only the usage blocks, model names, tool names, and timestamps
• It never writes anything except the report you asked for

If you're paranoid, the source is ~400 lines of zero-dependency Node. Read it.

Origin

This is a free standalone tool from the same author as Claude Operator — a production-grade CLAUDE.md and skill pack for senior engineering teams using Claude Code.

If you're shipping AI features and want the rest of the agent-quality story (a CLAUDE.md that stops "done" lies, 18 skills including db-migration-checker and n+1-finder, a verifier subagent that can't be talked into a soft PASS, a /ship gauntlet, and a hooks config that blocks rm -rf / and force-push) — the pack is $27 with a 7-day refund.

Get the full pack →

License

MIT.

Sister tools

Part of a small family of zero-dependency static-analysis CLIs:

• @yixi/token-doctor — this tool
• @yixi/env-doctor — .env drift + committed-secret detector
• @yixi/dockerfile-doctor — Dockerfile production-safety linter

See also

• ccusage — Claude Code usage statistics
• claude-usage — basic cost summarizer

@yixi/token-doctor differs by surfacing waste signals with dollar estimates rather than only reporting totals.

Limitations

• Pricing changes silently when Anthropic updates their pricing page. Always cross-check large totals against the official Anthropic console.
• Tokens reported in JSONL usage blocks are what the Claude API returns; if the API undercounts (it shouldn't, but bugs happen), this tool undercounts too.
• Tool-use vs. chat-only categorization treats turns with multiple content blocks as one category by precedence: tool_use > thinking > text. A turn with both text and thinking is chat-thinking; a turn with only text is chat-only.
• Cross-tool support (Cursor, Codex CLI, Aider) is on the roadmap but not in v0.1.