# tokenscope **Category:** ๐Ÿ’ฐ Finance & Fintech **Repository:** https://github.com/wartzar-bee/tokenscope **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/tokenscope ## Description Analyze Claude Code token cost & context attribution. Local, read-only MCP server. ## Claude Desktop Quick Installation Heuristic fallback โ€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "tokenscope": { "command": "npx", "args": ["-y","tokenscope"] } } ``` ## Documentation & README # 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 being **re-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.)* ## Why Agentic coding (Claude Code, etc.) produces surprise bills, and the cause is mundane: as a session grows, the **whole context is re-sent every turn**, so cost balloons even when the model writes little. Existing dashboards show *totals*; tokenscope shows the **attribution** โ€” 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) ``` npx @wartzar-bee/tokenscope --demo ``` 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.) ## Install / run No install โ€” runs via npx: ``` 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 # 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. ## Local cost gate (pre-push / pre-commit) `--max-total N` / `--max-delta N` make `scan` **exit 1** when the token footprint (or a diff's delta) blows a budget โ€” the same check [ci-guardrail](https://github.com/wartzar-bee/ci-guardrail) runs in CI, but locally, before you push. Wire the absolute budget into a git hook so a runaway prompt/config never leaves your machine: ```sh # .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; } ``` Under budget it prints the report and exits 0; over budget it prints a `BLOCKED:` line and exits 1. Without a `--max-*` flag `scan` just reports (exit 0), so it's opt-in. `--max-delta` gates the delta between **two directories on disk** (`scan --diff --max-delta N`) โ€” point it at a checked-out base tree when you want a regression gate rather than an absolute cap. Using the [pre-commit](https://pre-commit.com) framework? Add tokenscope to your `.pre-commit-config.yaml` โ€” no git-hook scripting: ```yaml 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 ``` `language: node`, zero dependencies. With no `args` it prints the footprint (exit 0); add `--max-total N` (or `--diff --max-delta N`) to fail the commit over budget. ## Share your bill (privacy-safe) `--share` emits a compact summary built from **aggregate numbers only** โ€” **no file paths, no prompt/response content** โ€” so it's safe to paste in public: - **Markdown** for 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-contained **SVG "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 at [tokenscope.pages.dev/benchmark](https://tokenscope.pages.dev/benchmark/). Prefer not to touch a terminal flag? The same render runs **entirely in your browser** at the web surface in [`web/`](https://github.com/wartzar-bee/tokenscope/blob/HEAD/web/): paste your `--json` output and it draws the full report + the SVG card locally โ€” nothing is uploaded. ## Use it from an AI agent (MCP server) There's an [**MCP server**](https://github.com/wartzar-bee/tokenscope/blob/HEAD/mcp/) that exposes the same engine to AI agents / MCP clients (Claude Desktop, Claude Code, etc.) as tools: `analyze_claude_cost`, `get_cost_benchmark`, and `tokenscope_share_summary`. Add it to your MCP config: ```json { "mcpServers": { "tokenscope": { "command": "npx", "args": ["-y", "@wartzar-bee/tokenscope-mcp"] } } } ``` Then ask your agent *"use tokenscope to analyze my last Claude Code session."* It's the same local, read-only engine โ€” see [`mcp/README.md`](https://github.com/wartzar-bee/tokenscope/blob/HEAD/mcp/README.md). ## Pricing Uses documented default prices (Anthropic cache multipliers: write 1.25ร—/2ร—, read 0.1ร— of input). **Verify and override** for your exact model/tier via `./.tokenscope.json`: ```json { "pricing": { "claude-opus-4": { "in": 15, "out": 75 } } } ``` Unknown models are flagged (never silently counted as $0). Token counts are read straight from the logs; cost = those counts ร— the prices shown. ## Part of the wartzar-bee cost toolkit tokenscope is the measurement engine behind a sibling tool, and one of three open-source cost projects: - [**ci-guardrail**](https://github.com/wartzar-bee/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**](https://github.com/wartzar-bee/enclave) โ€” the security-first, self-hosted runtime & sandbox the wartzar-bee agent fleet runs on (Apache-2.0). If you find tokenscope useful, ci-guardrail is the zero-config way to run it on every PR. ## Why this exists โ€” further reading tokenscope came out of running autonomous agents and watching the bill. The write-ups behind it: - [I put an agent on a timer โ€” overnight it burned 136M tokens doing almost nothing](https://dev.to/wartzarbee/i-put-an-ai-agent-on-a-timer-overnight-it-burned-136m-tokens-doing-almost-nothing-2ae2) โ€” the runaway-cost postmortem that started this. - [Where your Claude Code bill actually goes โ€” I measured 66 of my own sessions](https://dev.to/wartzarbee/where-your-claude-code-bill-actually-goes-i-measured-66-of-my-own-sessions-471e) โ€” the empirical breakdown tokenscope automates. - [The Claude Code cost formula: why the same session can cost 10ร— more tomorrow](https://dev.to/wartzarbee/the-claude-code-cost-formula-why-the-same-session-can-cost-10x-more-tomorrow-16df) โ€” the cost mechanics tokenscope surfaces. - [Cost-audit series](https://dev.to/wartzarbee/langchain-cost-audit-what-conversationbuffermemory-actually-costs-you-at-scale-4f8n) โ€” reproducible token-cost audits of popular agent frameworks (LangChain, AutoGen, CrewAI, โ€ฆ). - [Catch token-cost regressions in CI before they ship](https://dev.to/wartzarbee/catch-token-cost-regressions-in-ci-before-they-ship-35o3) โ€” tokenscope as a GitHub Action cost gate on your PRs. ## Status / roadmap - v0.1: Claude Code session cost + context attribution + insights. **20/20 unit tests** on the cost math (`npm test`). - Next (evidence-driven): per-tool/-file token attribution; daily/budget alerts; a `--watch` live meter; OpenAI/Codex log support. MIT. Not affiliated with Anthropic.