{
  "markdown": "# tokenscope ⏣\n\n**See what your AI-coding session actually cost — and what's eating your context.**\nA 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).\n\n```\n$ npx @wartzar-bee/tokenscope\n\n  tokenscope ⏣  latest session\n  ──────────────────────────────────────────────────────\n  Total cost   $868.84   over 967 model turns\n\n  Where the money went\n  output (model writing)     ████░░░░░░░░░░░░░░░░░░░░  16%  $137.24\n  cache read (re-sent ctx)   ████████████████░░░░░░░░  66%  $577.59\n  cache write (new ctx)      ████░░░░░░░░░░░░░░░░░░░░  18%  $153.67\n\n  Context size per turn  (peak 822k · avg 404k · now 822k tokens)\n  ▁▁▁▁▁▂▂▂▂▂▂▂▃▃▃▃▃▃▃▄▄▄▄▄▅▅▅▅▅▆▆▆▆▇▇▇▇▇▇█\n\n  Insights\n  • Re-sent (cached) context cost $577.59 (66% of spend) — context re-read every turn.\n  • Peak context ~822k tokens — /compact or a fresh session would cut per-turn cost.\n  • Only 16% of spend is the model's actual output.\n```\n*(A real session, default Opus pricing. Your numbers will differ — prices are overridable.)*\n\n## Why\nAgentic 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.\n\n## Try it in 10 seconds (no Claude Code logs needed)\n```\nnpx @wartzar-bee/tokenscope --demo\n```\nRuns 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.)\n\n## Install / run\nNo install — runs via npx:\n```\nnpx @wartzar-bee/tokenscope               # your most recent Claude Code session\nnpx @wartzar-bee/tokenscope --demo        # a bundled sample session — no logs needed\nnpx @wartzar-bee/tokenscope --all         # aggregate every session\nnpx @wartzar-bee/tokenscope <file|dir>    # a specific session .jsonl\nnpx @wartzar-bee/tokenscope --version     # print the installed version and exit\nnpx @wartzar-bee/tokenscope --json        # machine-readable\nnpx @wartzar-bee/tokenscope --share       # privacy-safe shareable summary (markdown + SVG card)\nnpx @wartzar-bee/tokenscope --share-svg   # just the SVG \"cost report card\"\nnpx @wartzar-bee/tokenscope scan          # static token footprint of a source dir (the engine behind ci-guardrail)\nnpx @wartzar-bee/tokenscope scan --diff ../base   # cost delta of the current dir vs a base dir — catch a regression before you push\nnpx @wartzar-bee/tokenscope scan --max-total 50000            # exit 1 if the footprint exceeds a budget — a local cost gate\nnpx @wartzar-bee/tokenscope scan --diff ../base --max-delta 2000   # exit 1 if the diff adds more than N tokens\n```\nReads `~/.claude/projects/**/*.jsonl`. **Read-only, local, no network, no telemetry** — open the source; nothing leaves your machine.\n\n## Local cost gate (pre-push / pre-commit)\n`--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:\n```sh\n# .git/hooks/pre-push  (chmod +x)\nnpx -y @wartzar-bee/tokenscope scan --dir prompts --max-total 50000 \\\n  || { echo \"prompt token footprint over budget — trim before pushing\"; exit 1; }\n```\nUnder 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 <baseDir> --max-delta N`) — point it at a checked-out base tree when you want a regression gate rather than an absolute cap.\n\nUsing the [pre-commit](https://pre-commit.com) framework? Add tokenscope to your `.pre-commit-config.yaml` — no git-hook scripting:\n```yaml\nrepos:\n  - repo: https://github.com/wartzar-bee/tokenscope\n    rev: v0.2.6\n    hooks:\n      - id: tokenscope\n        args: [\"--dir\", \"prompts\", \"--max-total\", \"50000\"]   # optional — omit to just report\n```\n`language: node`, zero dependencies. With no `args` it prints the footprint (exit 0); add `--max-total N` (or `--diff <baseDir> --max-delta N`) to fail the commit over budget.\n\n## Share your bill (privacy-safe)\n`--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:\n- **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\").\n- A self-contained **SVG \"cost report card\"** (`--share-svg`) — no binary deps; renders inline on GitHub and is trivially shareable.\n- **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/).\n\nPrefer not to touch a terminal flag? The same render runs **entirely in your browser** at the web surface in [`web/`](web/): paste your `--json` output and it draws the full report + the SVG card locally — nothing is uploaded.\n\n## Use it from an AI agent (MCP server)\nThere's an [**MCP server**](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:\n```json\n{ \"mcpServers\": { \"tokenscope\": { \"command\": \"npx\", \"args\": [\"-y\", \"@wartzar-bee/tokenscope-mcp\"] } } }\n```\nThen ask your agent *\"use tokenscope to analyze my last Claude Code session.\"* It's the same local, read-only engine — see [`mcp/README.md`](mcp/README.md).\n\n## Pricing\nUses 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`:\n```json\n{ \"pricing\": { \"claude-opus-4\": { \"in\": 15, \"out\": 75 } } }\n```\nUnknown models are flagged (never silently counted as $0). Token counts are read straight from the logs; cost = those counts × the prices shown.\n\n## Part of the wartzar-bee cost toolkit\ntokenscope is the measurement engine behind a sibling tool, and one of three open-source cost projects:\n- [**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`.\n- [**enclave**](https://github.com/wartzar-bee/enclave) — the security-first, self-hosted runtime & sandbox the wartzar-bee agent fleet runs on (Apache-2.0).\n\nIf you find tokenscope useful, ci-guardrail is the zero-config way to run it on every PR.\n\n## Why this exists — further reading\ntokenscope came out of running autonomous agents and watching the bill. The write-ups behind it:\n- [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.\n- [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.\n- [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.\n- [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, …).\n- [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.\n\n## Status / roadmap\n- v0.1: Claude Code session cost + context attribution + insights. **20/20 unit tests** on the cost math (`npm test`).\n- Next (evidence-driven): per-tool/-file token attribution; daily/budget alerts; a `--watch` live meter; OpenAI/Codex log support.\n\nMIT. Not affiliated with Anthropic.\n",
  "bytes": 8959,
  "sha": "43917b3214067e4615bfa5439c6803b00680fe675e0a58a0e0eeca18296715bc",
  "repo_slug": "wartzar-bee/tokenscope",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wartzar_bee_tokenscope_9d2688fa/readme"
}