tokendoctor
同样的 Claude Code,费用最多降低 38%
看看你的 Claude Code 用法在哪里多花了钱,修好它,随时可以撤销。在你自己的机器上运行。
Website · Install · Changelog

| 按 API 标价计算的每次请求主线程成本,对比 400K 窗口和子代理使用 Sonnet 之前的一个月与之后的一周 | −38% |
|---|---|
| 每次请求的上下文 | 412K → 219K |
| 同样的会话在 400K 窗口下重放:只改变了窗口 | 主线程 −33%,全部开销 −20% |
| 与摘要方案对比,同样的一个工作日( bench ) | 成本 −19%,时间 −33% |
| bench 中一周的工作(27 步),原版 Claude Code 对比应用所有修复并加上摘要方案 | 成本 −11 到 −21%(2 次和 3 次运行的中位数;单次运行 −40% 到 +17%),所有测试通过 |
没有什么万能药。如果你的会话很少超过 400K token,窗口对你没有任何改变;一个正好在你快要完成时触发的摘要,可能省得还没有花得多;你的模型、投入程度和工作内容都会让这个数字变化。所以 tokendoctor 先给你看你自己的数据:/tokendoctor:sessions 会在做任何改动之前,用更小的窗口重放你自己的会话。
/tokendoctor:dashboard:按天、模型、投入程度、主线程和每个子代理、上下文大小和项目查看每一个 token。一个本地文件;这是作者自己的数据。

Install
claude plugin marketplace add localixai/tokendoctor
claude plugin install tokendoctor@tokendoctor
用 claude plugin marketplace update tokendoctor 和 claude plugin update tokendoctor@tokendoctor 更新,然后重启 Claude Code。想不安装先试用,可以克隆仓库并运行 claude --plugin-dir /path/to/tokendoctor。
Use
| 命令 | 作用 |
|---|---|
| /tokendoctor:sessions [days] | 更小的窗口本来能为你省下多少(重放你的会话),然后看过去 30 天(或 days 天)token 去了哪里,并附带发现。只读。 |
| /tokendoctor:audit | 按严重程度进行设置检查,每一项都链接到文档,读取你的 memory 和 CLAUDE.md,然后是使用仪表盘。只读。 |
| /tokendoctor:dashboard [days] | 构建并打开这台机器上每个会话的本地仪表盘:按天、token 类型、模型、推理投入、主线程和每个子代理类型、上下文大小、项目和小时统计的开销,带筛选。一个 HTML 文件,不联网。 |
| /tokendoctor:optimize [focus] | 根据你的数字提出最多五项改动,并应用你选中的那些。 |
| /tokendoctor [name] [value] | 显示主要设置,解释某一项或修改它。不调用模型,不消耗 token。 |
| /tokendoctor fix <finding-id> | 在展示之后应用一项审计修复,并备份该文件。 |
| /tokendoctor undo [n] | 列出 tokendoctor 做过的改动,最新的在前,并把第 n 项改动还原。 |
/tokendoctor 由插件自身应答,所以不消耗任何东西。Tab 会补全名称(window、slide、cache、effort、model、subagents,以及用 /tokendoctor all 补全其余项)及其取值;/tokendoctor window 400k 按输入的内容生效,/tokendoctor window reset 回到默认值,--project 或 --local 写入那里而不是你的用户设置。模型名必须是别名(opus、sonnet、haiku)或 claude-… 形式的 id。
optimize 只修改可调列表和 /config 行中的设置。每项改动都会打开一个对话框展示它,并且只在点 Apply 时才执行;没有人可以询问时,比如在 -p 运行中,什么都不会改。Hooks 和权限永远不在列表上。
插件启用期间,它的 bin/ 目录位于 Bash 工具的 PATH 中:
tokendoctor-audit [--project <dir>] [--json]
tokendoctor-sessions [--days <n>] [--project <dir>] [--by day|week] [--json]
tokendoctor-set --list | <key> <value>|--unset [--scope user|project|local] [--write]
tokendoctor-apply <finding-id> [--scope user|project|local] [--project <dir>] [--write]
tokendoctor-undo [--json] | <n> [--write]
tokendoctor-replay [--days <n>] [--window 200k,400k] [--json] # what a smaller window would have saved
tokendoctor-org-install [--write] [--uninstall] # the slide under a Team/Enterprise login (see below)
tokendoctor-selfcheck [--log <file>] [--json] # what really loaded, from a debug log (one small Haiku request, or a log you have)
这些技能仅由用户调用(disable-model-invocation)。claude plugin details tokendoctor@tokendoctor 估计这五个技能的常驻开销约为 235 tokens。该插件没有 MCP server。它的 hooks 模块将 optimize 工具(mcp__tokendoctor__*)放在 ToolSearch 之后,因此在 /tokendoctor:optimize 加载它们之前,只会列出它们的名称。/tokendoctor 和 slide 也在 hooks 模块中运行,不调用模型,因此不会增加 tokens。它唯一的一个命令 hook 会在会话开始时在后台运行 tokendoctor-record。该 hook 是异步的并且不打印任何内容,因此不会增加 tokens。它会把每个已完成日期的汇总追加到 ~/.claude/tokendoctor/history.jsonl,因此趋势数据能比 Claude Code 的对话记录清理保留得更久。
错误表示设置错误或被忽略,警告很可能造成真实花费,提示则值得一看。依赖某个 Claude Code 版本的规则在旧版本上会被跳过。
| 发现项 | 严重程度 | 能捕获的问题 |
|---|---|---|
| settings-unreadable | error | 设置文件存在但不是有效的 JSON,因此其中的内容都不会生效。 |
| compact-threshold-undocumented | error | autoCompactThreshold 不是 Claude Code 的设置项;真正的键是 autoCompactWindow 。修复会将其移除。 |
| compact-env-bare-number | error | CLAUDE_CODE_AUTO_COMPACT_WINDOW 低于 100,000(裸数字表示 token 数,而非千数)。 |
| compact-window-unset | warn | 原生窗口为 1M 的模型默认只在接近 967K 时才压缩。修复会将其设为 400,000。 |
| compact-window-small | warn | 窗口过小,频繁压缩会破坏 prompt cache。 |
| prompt-caching-disabled | warn | 设置了某个 DISABLE_PROMPT_CACHING* 变量。 |
| subagent-model-force | warn | 每个子代理(包括推理类子代理)都被强制使用同一个模型。 |
| effort-max-in-settings | warn | 设置中不接受 effortLevel: "max"。修复改用 xhigh 。 |
| advisor-inactive | warn | 顾问会静默地不运行(遥测或功能开关获取被关闭、顾问模型低于主模型、工具被禁用)。 |
| fast-mode-enabled | warn | fastMode: true 被保存为默认值,因此每个会话都要支付更高的 fast-mode 费率。修复会设置 fastModePerSessionOptIn 。 |
| auto-compact-off | warn | DISABLE_AUTO_COMPACT 或 autoCompactEnabled: false :历史会持续增长,直到填满模型窗口。修复会取消该设置。 |
| tool-search-off | warn/info | ENABLE_TOOL_SEARCH=false 会把每个 MCP 工具定义都加载进每个请求。 |
| explore-default-model | info | 内置的 Explore 代理在许多账户上运行于 Opus。修复会安装一个 Haiku 的只读覆盖。 |
| subagent-model-unset | info | 通用子代理会继承昂贵的主模型。修复会设置 CLAUDE_CODE_SUBAGENT_MODEL=sonnet 。 |
| main-model-expensive | info | 默认模型为 Opus 或 Fable;建议改用 Sonnet。 |
| agents-inherit-model | info | 未指定模型的自定义代理会运行在主模型上。 |
| heavy-dirs-not-denied | info | 大型的 target/ 、 dist/ 、 build/ 、 coverage/ 、 .turbo/ 目录未被排除在读取之外。修复会添加 permissions.deny 规则。 |
| large-lockfile-readable | info | 超过 200 KB 的锁文件,模型可以完整打开。修复会添加一条 deny 规则。 |
| instructions-long | info | CLAUDE.md 加上其 @imports 超过 200 行。按路径限定的 .claude/rules 和 skills 能降低成本;imports 不能。 |
| compact-instructions-missing | info | 没有 # Compact instructions 章节来引导摘要。 |
| context-surface | info | 每个会话都加载了大量 skills、plugins 或 MCP servers。 |
| duplicate-skills | info | 同一个 skill 同时存在于用户级和项目级。 |
| thinking-tokens-env | info | MAX_THINKING_TOKENS 在自适应推理模型上会被忽略。 |
| prompt-cache-ttl-forced-short | info | FORCE_PROMPT_CACHING_5M 会移除某些套餐享有的一小时缓存。 |
| agent-teams-enabled | info | agent teams 会让每个队友成倍增加 token 用量。 |
| mcp-output-limit-raised | info | 被调高的 MAX_MCP_OUTPUT_TOKENS 。 |
| every-tool-hooks | info | 匹配工具事件上 * 的 hooks(Pre/PostToolUse、PostToolUseFailure、PermissionRequest)会在每次调用时启动一个进程。这是延迟问题,不是 token 问题。修复会在试运行后移除它们;如果某个工具通过这些 hooks 显示代理状态,请先阅读警告。 |
| idle-compaction-off | info | idleCompaction: false :长对话在其一小时缓存过期前不会被压缩。修复会取消该设置。 |
| bash-output-raised | info | bashOutputMaxChars 或 BASH_MAX_OUTPUT_LENGTH 高于 30,000 默认值。 |
| code-intelligence-missing | info | 项目包含某种语言的文件,且该语言有官方 language-server 插件( typescript-lsp 、 pyright-lsp 、 gopls-lsp 、……),但该插件未启用。 |
templates/statusline.sh 是修复程序安装到你的 Claude 配置文件夹中的状态栏脚本。templates/agents/ 包含三个通用子代理(Explore、test-runner、docs-lookup),每个都固定使用一个小模型,并配有只读或范围很窄的工具。插件不能覆盖内置代理,也不能附带 autoCompactWindow、env 或 permissions 这类 settings.json 键,因此 apply 步骤会把模板复制到 ~/.claude/agents/ 或 .claude/agents/,并自行编辑你的设置文件,同时做备份。
Claude Code 每隔几天就会变化,因此审计不信任插件中冻结的列表:
- 它会从 code.claude.com 读取当前的设置参考和环境变量列表,格式为 Markdown(每个文档页面都位于 …/docs/en/<page>.md,模型索引位于 llms.txt;像 context7 这样的镜像会按自己的计划重新索引)。在 ~/.claude/tokendoctor/docs 中缓存一天;--offline 仅使用缓存。只抓取这些公开页面;不会发送任何内容。它会标记 Claude Code 未记录的设置键(settings-key-undocumented:拼错或已删除的键不起作用)、它不认识的 Claude Code 自有系列变量(env-undocumented),以及需要比你当前版本更新的版本才能使用的键(setting-needs-newer-version)。
- 它会读取最近一天的 claude --debug 日志(如果你有的话),而 tokendoctor-selfcheck 会生成一份(在 Haiku 上发起一次 claude -p 请求,且不保存会话;--log <file> 读取你已有的一份,不产生费用):加载的是哪一份 tokendoctor 以及处于哪个层级,内置防护是否已就位,压缩时 mod 的顺序,被跳过的 hooks,Claude Code 实际在哪个窗口执行压缩,以及技能列表是否超出预算(描述被截短)。
- /tokendoctor:audit 和 /tokendoctor:optimize 技能在解释或推荐某项发现之前,会先读取该发现的文档页面。
- 对于维护 tokendoctor 的人,npm run docs:check 会对照当前文档检查它提到的每个设置键和变量。
| Finding | Severity | What it catches |
|---|---|---|
| late-compaction | warn | 超过 30% 的主线程成本花在上下文中超过 400K tokens 的情况下。 |
| subagents-on-top-model | warn | 子代理使用 Opus 或 Fable,产生超过全部成本 5% 的费用。分叉始终运行在主模型上。 |
| long-sessions | info | 500+ 轮的会话,以及它们在成本中的占比。 |
| idle-cache-rebuilds | info | 提示缓存在中断期间过期后被重建。 |
| images-read-repeatedly | info | 同一张图片被读取三次或更多次。 |
| rereads-after-compaction | info | 在摘要之前读取、并在接下来 10 个请求内再次读取的文件:摘要丢失的内容。有幻灯片时,会对照幻灯片显示。 |
默认关闭。使用 /tokendoctor slide on(或 tokendoctor-set tokendoctor.slide true --write,或 /tokendoctor:optimize)后,在 Claude Code 原本会压缩的地方,插件的 hooks 模块会把旧的工具输出省略成简短的指针,而不是进行摘要,做法与 llx 一样。每个提示、回答和决策都逐字保留,且没有摘要停顿。
- 先处理什么:因之后对同一文件的读取或编辑而变得过时的读取,然后是编辑写入的内容(它已在磁盘上),然后是最旧的输出。最近的尾部、模型尚未回答的输出以及 Agent 结果会保留。
- 它会释放到 Claude Code 压缩点的 tokendoctor.slideTo 百分比(默认 25),因此 slide 很少发生。每次 slide 都会像摘要一样重新发送一次上下文;指针之后不会再被改动。
- /compact 仍会进行摘要,无法释放足够空间的 slide 也会如此。使用 autoCompactWindow 设置更小的窗口(例如 400000),slide 会基于它工作。
- 它也会处理空闲压缩(在一小时的缓存过期之前);/compact 和插件的 $.session.compact 仍会进行摘要。
文章标题:Tokendoctor——同样的 Claude Code,费用最高省 38%
正文:
- Team 和 Enterprise 登录,以及带受管设置的机器。在这类环境下,Claude Code 会把内置防护 cc-plugin-sec-default 排在你自己安装的 mod 之前,并让压缩流程绕过它们:slide 无法运行,审计结果和 /tokendoctor slide 都会说明这一点。tokendoctor-org-install 会把 tokendoctor 安装为机器自身的 mod,它在防护之后运行:系统文件夹中一份 root 所有的副本,以及带 appendPlugins 的 managed-settings.d/50-tokendoctor.json(先试运行,再执行一条 sudo 命令;--uninstall 可撤销)。如果你的组织下发自己的受管设置,这些文件会被忽略,只有管理员才能添加它。
在一次真实会话中、相同大小下:Claude Code 的摘要耗时 65.3 s,把 367K 压到 35K;slide 耗时 0.04 s,把 368K 压到 36K。作者真实会话中的摘要平均耗时 79 s(共 109 次,9 月 22 日至 11 月 1 日)。
在 bench/ 上,Claude Code 针对固定的验收测试做一个 TypeScript 项目,Haiku 5.5,100K 窗口以便多次压缩(取中位数)。只压缩一次的短任务省时间但不省钱;工作越长,slide 省得越多:
| 任务 | 分支 | 通过的测试 | 成本 | 时间 | 等待压缩 |
|---|---|---|---|---|---|
| 一天的工作(7 个请求,307 个测试),2 次运行 | 摘要 | 307/307 | $0.186 | 1141 s | 103–137 s |
| slide | 307/307 | $0.151(−19%) | 763 s(−33%) | 不到 1 s | |
| evalkit(一个 eval harness,238 个测试),5 次和 3 次运行 | 摘要 | 238/238 | $0.149 | 656 s | 约 50 s |
| slide | 238/238 | $0.096(−35%) | 472 s(−28%) | 不到 1 s | |
| fixkit(12 个待找 bug,238 个测试),5 次运行 | 摘要 | 238/238 | $0.037 | 154 s | 约 16 s |
| slide | 238/238 | $0.039(+6%) | 128 s(−17%) | 不到 1 s |
更早、规模更小的 node bench/window.mjs 运行(60 个 300 行的文件逐个读取,然后在同一会话中做一次后续追问,200K 窗口)两种方式成本相同:
| 模型 | 分支 | 成本 | 压缩次数 | 回答正确 |
|---|---|---|---|---|
| Haiku 5.5(3 次运行) | 摘要 | $0.581 | 3 | 5/5 |
| Haiku 5.5(3 次运行) | slide 至 25% | $0.580 | 3.7 | 5/5 |
| Sonnet 5.5(1 次运行) | 摘要 | $2.93 | 3 | 5/5 |
| Sonnet 5.5(1 次运行) | slide 至 25% | $2.99 | 3 | 5/5 |
摘要会丢失什么,用 --task recall 测量:会话开始时由人给出五个决定,文件读完后被删除,后续追问要求说出这些决定以及模型记下的八个 KEY。Claude Code 的摘要全部保留:在两个模型上的每次运行中都是 6/6 和 8/8。slide 在 Haiku 5.5 上表现相同(3 次运行,贵 2%);在 Sonnet 5.5 上(1 次运行)它漏掉了一个 KEY,模型在 slide 之后的第一次回复中没有记下它。到目前为止,没有测试显示 slide 回答得更好或更差:它省的是时间和钱,不是质量。
- 它会读取用户、项目和本地设置文件、~/.claude.json(其中的 MCP 服务器名称用于计数,plan 类型用于判断 Claude Code 的防护是否已就位)、系统文件夹中的受管设置文件以及缓存的服务端受管设置(仅用于找到防护及其自身的机器副本),还有你的 skill 和 agent 文件夹。对于受管设置,它不会按规则检查。
- 审计每天抓取两个 Claude Code 文档的公开页面(--offline 可跳过);除此之外不通过网络传输任何东西,也不会发送你的任何内容。
- 一条规则是否有帮助取决于你的套餐和工作负载。检查结果会解释其中的取舍并附上文档链接;由你自己决定。
- permissions.deny 中的 Deny 规则对搜索工具是尽力而为,并不能阻止通过 Bash 进行的读取。
- 成本按各模型 Claude API 目录价的美元计算(lib/prices.mjs:在 Opus 5.5 和 Sonnet 5.5 上缓存读取为输入的 0.05x,在 Fable 5.1 上为 0.025x,Haiku 5.5 按 prompt 长度计价,fast mode、仅美国推理、web search)。在 Pro 或 Max 套餐上,这就是同样的工作在 API 上要花的钱:Anthropic 不公布套餐限额如何衡量各类 token。
Tokendoctor – 同样的 Claude Code,最高可便宜 38%
- Claude Code 会为一些没有写入对话记录的请求计费:摘要压缩自身的请求、标题、为 WebFetch 读取页面的小模型。它们的成本是 Claude Code 自身的会话总计(其 cost-state 行)减去对话记录中的响应(在该总计可靠的情况下);否则,摘要根据其读取的上下文估算。与 Claude Code 在 bench 的 78 次运行中报告的成本相比:77 次精确到分一致,1 次高出 7.7%。
- 其他机器上的会话以及 Claude Code 已经清理掉的对话记录不计入,除非这些天已经存在于历史文件中。
npm test # node's built-in test runner, no dependencies
npm run test:mod # the hooks module's tests (claude plugin test)
claude plugin validate .
bun bench/run.ts --task fixkit --window 100000 --arm factory --arm factory+slide # see bench/README.md
如果 git 将要提交的任何内容包含 API key 或 token、主目录路径或机器的临时文件夹,test/private.test.mjs 就会失败:基准测试结果来自某人的账户上的运行,因此只提交它们的摘要,对话记录保留在本地。
落地页位于 site/(cd site && npm install && npm run dev;npm run build 会预渲染它,node scripts/og.mjs 会重绘社交卡片)。演示是用 asciinema 录制的真实会话;site/scripts/RECORDING.md 说明了如何再次录制它。
规则是作用于快照的纯函数(lib/rules.mjs);读取磁盘的代码位于 lib/collect.mjs,写入的代码位于 lib/apply.mjs。添加一条规则意味着添加一个条目及其测试。会话分析位于 lib/sessions.mjs 和 lib/history.mjs,tokendoctor-set 可能修改的设置位于 lib/tunables.mjs,/tokendoctor 命令位于 lib/console.mjs,回放位于 lib/replay.mjs,slide 位于 hooks/window.ts,优化工具位于 hooks/register.ts。