Tokenscope

See what your AI-coding session actually cost — and what's eating your context.A local, read-only CLI that parses your Claude Code session logs and shows where the money goes: model output vs. context beingre-sent every turn(the hidden 60%+ of most bills).

$ npx @wartzar-bee/tokenscope tokenscope ⏣ latest session ────────────────────────────────────────────────────── Total cost $868.84 over 967 model turns Where the money went output (model writing) ████░░░░░░░░░░░░░░░░░░░░ 16% $137.24 cache read (re-sent ctx) ████████████████░░░░░░░░ 66% $577.59 cache write (new ctx) ████░░░░░░░░░░░░░░░░░░░░ 18% $153.67 Context size per turn (peak 822k · avg 404k · now 822k tokens) ▁▁▁▁▁▂▂▂▂▂▂▂▃▃▃▃▃▃▃▄▄▄▄▄▅▅▅▅▅▆▆▆▆▇▇▇▇▇▇█ Insights • Re-sent (cached) context cost $577.59 (66% of spend) — context re-read every turn. • Peak context ~822k tokens — /compact or a fresh session would cut per-turn cost. • Only 16% of spend is the model's actual output.

(A real session, default Opus pricing. Your numbers will differ — prices are overridable.)

Agentic coding (Claude Code, etc.) produces surprise bills, and the cause is mundane: as a session grows, thewhole context is re-sent every turn, so cost balloons even when the model writes little. Existing dashboards showtotals; tokenscope shows theattribution— output vs. cache-read vs. cache-write vs. fresh input, the per-turn context-growth curve, cost by model, subagent spend, and which tools fill your context — with concrete "trim this" insights.

Try it in 10 seconds (no Claude Code logs needed)

Runs on a bundled sample session so you see the full report before pointing it at your own logs — no setup, nothing to configure. (The sample is synthetic, for demonstration.)

npx @wartzar-bee/tokenscope # your most recent Claude Code session npx @wartzar-bee/tokenscope --demo # a bundled sample session — no logs needed npx @wartzar-bee/tokenscope --all # aggregate every session npx @wartzar-bee/tokenscope <file|dir> # a specific session .jsonl npx @wartzar-bee/tokenscope --version # print the installed version and exit npx @wartzar-bee/tokenscope --json # machine-readable npx @wartzar-bee/tokenscope --share # privacy-safe shareable summary (markdown + SVG card) npx @wartzar-bee/tokenscope --share-svg # just the SVG "cost report card" npx @wartzar-bee/tokenscope scan # static token footprint of a source dir (the engine behind ci-guardrail) npx @wartzar-bee/tokenscope scan --diff ../base # cost delta of the current dir vs a base dir — catch a regression before you push npx @wartzar-bee/tokenscope scan --max-total 50000 # exit 1 if the footprint exceeds a budget — a local cost gate npx @wartzar-bee/tokenscope scan --diff ../base --max-delta 2000 # exit 1 if the diff adds more than N tokens

Reads~/.claude/projects//.jsonl.Read-only, local, no network, no telemetry— open the source; nothing leaves your machine.

# .git/hooks/pre-push (chmod +x) npx -y @wartzar-bee/tokenscope scan --dir prompts --max-total 50000 \ || { echo "prompt token footprint over budget — trim before pushing"; exit 1; }

repos: - repo: https://github.com/wartzar-bee/tokenscope rev: v0.2.6 hooks: - id: tokenscope args: ["--dir", "prompts", "--max-total", "50000"] # optional — omit to just report

--shareemits a compact summary built fromaggregate numbers only—no file paths, no prompt/response content— so it's safe to paste in public:

- Markdownfor Reddit / Discord / a GitHub issue (total, the output/cache-read/cache-write/fresh split with %, peak/avg context, and the headline "X% of spend was re-sent context").
- A self-containedSVG "cost report card"(--share-svg) — no binary deps; renders inline on GitHub and is trivially shareable.
- How you compare— both forms now answer "is my session unusual?" against a shipped, offline reference set of real sessions (e.g."more cache-efficient than ~80% of measured sessions; median session re-sends 24%"). It's a reference yardstick, not a census — full honest distribution attokenscope.pages.dev/benchmark.

Prefer not to touch a terminal flag? The same render runsentirely in your browserat the web surface inweb/: paste your--jsonoutput and it draws the full report + the SVG card locally — nothing is uploaded.

There's anMCP serverthat exposes the same engine to AI agents / MCP clients (Claude Desktop, Claude Code, etc.) as tools:analyze_claude_cost,get_cost_benchmark, andtokenscope_share_summary. Add it to your MCP config:

{ "mcpServers": { "tokenscope": { "command": "npx", "args": ["-y", "@wartzar-bee/tokenscope-mcp"] } } }

{ "pricing": { "claude-opus-4": { "in": 15, "out": 75 } } }

- ci-guardrail— a GitHub Action that runs tokenscope in CI to predict a pull request's token-cost delta and comment on the responsible files (report-only, or fail the build past a threshold):uses: wartzar-bee/ci-guardrail@v1.
- enclave— the security-first, self-hosted runtime & sandbox the wartzar-bee agent fleet runs on (Apache-2.0).

AI agent infrastructure suite — task deduplication, cost prediction, output validation, behavioral governance, shared failure intelligence. 5 products, 14 MCP tools, 1 API key.