Tokenscope

tokenscope ⏣

看看你的 AI 编码会话实际花了多少钱——以及什么内容占用了上下文。 一款本地、只读的 CLI，可解析你的 Claude Code 会话日志，并展示费用流向：模型输出与每轮重新发送的上下文（大多数账单中被隐藏的 60% 以上）。

$ 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.

（一个真实会话，按 Opus 默认价格计算。你的数据会有所不同——价格可以覆盖。）

为什么

Agentic 编码（Claude Code 等）会产生意外账单，原因却很普通：随着会话变长，每轮都会重新发送整个上下文，所以即使模型输出很少，费用也会激增。现有仪表板展示的是总额；tokenscope 展示的是费用归因——输出、缓存读取、缓存写入与新输入的占比、逐轮上下文增长曲线、按模型统计的费用、子 Agent 开销，以及哪些工具占用了你的上下文——并提供具体的“精简这里”建议。

10 秒快速体验（无需 Claude Code 日志）

npx @wartzar-bee/tokenscope --demo

它会使用内置示例会话运行，让你在指定自己的日志前就能看到完整报告——无需设置，也无需配置。（示例为合成数据，仅用于演示。）

安装 / 运行

无需安装——通过 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 <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

读取 ~/.claude/projects/**/*.jsonl。只读、本地运行、不联网、不收集遥测数据——源码开放；任何内容都不会离开你的设备。

本地费用门限（推送前 / 提交前）

--max-total N / --max-delta N 会让 scan 在令牌占用（或差异的增量）超出预算时以状态码 1 退出——与 ci-guardrail 在 CI 中运行的检查相同，但在本地、推送前执行。将绝对预算接入 git 钩子，避免失控的提示词/配置离开你的设备：

# .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; }

未超预算时，它会打印报告并以状态码 0 退出；超出预算时，它会打印一行 BLOCKED: 并以状态码 1 退出。不带 --max-* 标志时，scan 只报告数据（状态码 0），因此此功能默认不启用。--max-delta 会检查磁盘上两个目录之间的增量（scan --diff <baseDir> --max-delta N）——如果要设置回归门限而非绝对上限，请将它指向已检出的基准树。

使用 pre-commit 框架？将 tokenscope 添加到 .pre-commit-config.yaml——无需编写 git 钩子脚本：

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，零依赖。不设置 args 时，它会打印占用情况（状态码 0）；添加 --max-total N（或 --diff <baseDir> --max-delta N）即可在提交超出预算时失败。

分享你的账单（保护隐私）

--share 会生成仅包含汇总数据的精简摘要——不含文件路径，也不含提示词/响应内容——可以放心粘贴到公开平台：

• Reddit / Discord / GitHub issue 可用的 Markdown（总额、输出/缓存读取/缓存写入/新输入占比及百分比、上下文峰值/平均值，以及“X% 的费用来自重新发送的上下文”这一醒目数据）。
• 自包含的 SVG“费用报告卡”（--share-svg）——无需二进制依赖；可在 GitHub 上内嵌渲染，也便于分享。
• 对比情况——现在这两种形式都会根据随附的离线真实会话参考集，回答“我的会话是否不寻常？”（例如：“缓存效率高于约 80% 的已测会话；会话重新发送比例中位数为 24%”）。这只是参考标尺，并非普查——完整的真实分布见 tokenscope.pages.dev/benchmark。

如果不想使用终端标志，也可以直接在 web/ 中的网页界面完全通过浏览器完成同样的渲染：粘贴 --json 输出，它就会在本地绘制完整报告和 SVG 卡片——不会上传任何内容。

通过 AI Agent 使用（MCP 服务）

MCP 服务 会将同一引擎以工具形式提供给 AI Agent / MCP 客户端（Claude Desktop、Claude Code 等）：analyze_claude_cost、get_cost_benchmark 和 tokenscope_share_summary。将其添加到你的 MCP 配置中：

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

然后让你的 Agent *“使用 tokenscope 分析我最近的 Claude Code 会话。”*它使用的是同一个本地只读引擎——详见 mcp/README.md。

定价

使用文档中列出的默认价格（Anthropic 缓存倍率：写入为输入价格的 1.25×/2×，读取为输入价格的 0.1×）。请通过 ./.tokenscope.json 核实并覆盖，以匹配你的具体模型/档位：

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

未知模型会被标记（绝不会被默默计为 $0）。Token 数量直接从日志中读取；成本 = 这些数量 × 显示的价格。

wartzar-bee 成本工具集的一部分

tokenscope 是一个姊妹工具背后的测量引擎，也是三个开源成本项目之一：

• ci-guardrail — 一个 GitHub Action，可在 CI 中运行 tokenscope，预测拉取请求的 Token 成本变化，并指出相关文件（仅生成报告，或在超过阈值时让构建失败）：uses: wartzar-bee/ci-guardrail@v1。
• enclave — wartzar-bee Agent 集群运行其上的安全优先、可自托管的运行时和沙箱（Apache-2.0）。

如果你觉得 tokenscope 有用，ci-guardrail 是在每个 PR 上运行它的零配置方式。

为什么会有这个项目 — 延伸阅读

tokenscope 源于运行自主 Agent 并观察账单。以下是其背后的文章：

• 我让一个 Agent 定时运行——一夜之间，它几乎什么都没做，却消耗了 1.36 亿个 Token — 引发这个项目的失控成本复盘。
• 你的 Claude Code 账单究竟花在哪里——我测量了自己的 66 次会话 — tokenscope 自动化实现的实证分析。
• Claude Code 成本公式：为什么同一个会话明天可能贵 10 倍 — tokenscope 揭示的成本机制。
• 成本审计系列 — 对热门 Agent 框架（LangChain、AutoGen、CrewAI，……）进行可复现的 Token 成本审计。
• 在发布前于 CI 中捕获 Token 成本回归 — 将 tokenscope 用作 PR 的 GitHub Action 成本门禁。

状态 / 路线图

• v0.1：Claude Code 会话成本 + 上下文归因 + 洞察。成本计算通过 20/20 项单元测试（npm test）。
• 下一步（以证据为依据）：按工具/文件进行 Token 归因；每日/预算提醒；--watch 实时计量器；支持 OpenAI/Codex 日志。

MIT。与 Anthropic 无关联。