Newshot

Tokendoctor – 同样的 Claude Code,最高省 38%

Translation(model translation, not the source's own text)

tokendoctor

同样的 Claude Code,费用最多降低 38%

看看你的 Claude Code 用法在哪里多花了钱,修好它,随时可以撤销。在你自己的机器上运行。

Website · Install · Changelog

tokendoctor 在真实的 Claude Code 会话中:/tokendoctor:sessions,然后是每日趋势
tokendoctor 在真实的 Claude Code 会话中:/tokendoctor:sessions,然后是每日趋势
按 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。一个本地文件;这是作者自己的数据。

作者的 tokendoctor 仪表盘:57% 的开销来自 Claude 重读对话
作者的 tokendoctor 仪表盘:57% 的开销来自 Claude 重读对话

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-unreadableerror设置文件存在但不是有效的 JSON,因此其中的内容都不会生效。
compact-threshold-undocumentederrorautoCompactThreshold 不是 Claude Code 的设置项;真正的键是 autoCompactWindow 。修复会将其移除。
compact-env-bare-numbererrorCLAUDE_CODE_AUTO_COMPACT_WINDOW 低于 100,000(裸数字表示 token 数,而非千数)。
compact-window-unsetwarn原生窗口为 1M 的模型默认只在接近 967K 时才压缩。修复会将其设为 400,000。
compact-window-smallwarn窗口过小,频繁压缩会破坏 prompt cache。
prompt-caching-disabledwarn设置了某个 DISABLE_PROMPT_CACHING* 变量。
subagent-model-forcewarn每个子代理(包括推理类子代理)都被强制使用同一个模型。
effort-max-in-settingswarn设置中不接受 effortLevel: "max"。修复改用 xhigh 。
advisor-inactivewarn顾问会静默地不运行(遥测或功能开关获取被关闭、顾问模型低于主模型、工具被禁用)。
fast-mode-enabledwarnfastMode: true 被保存为默认值,因此每个会话都要支付更高的 fast-mode 费率。修复会设置 fastModePerSessionOptIn 。
auto-compact-offwarnDISABLE_AUTO_COMPACT 或 autoCompactEnabled: false :历史会持续增长,直到填满模型窗口。修复会取消该设置。
tool-search-offwarn/infoENABLE_TOOL_SEARCH=false 会把每个 MCP 工具定义都加载进每个请求。
explore-default-modelinfo内置的 Explore 代理在许多账户上运行于 Opus。修复会安装一个 Haiku 的只读覆盖。
subagent-model-unsetinfo通用子代理会继承昂贵的主模型。修复会设置 CLAUDE_CODE_SUBAGENT_MODEL=sonnet 。
main-model-expensiveinfo默认模型为 Opus 或 Fable;建议改用 Sonnet。
agents-inherit-modelinfo未指定模型的自定义代理会运行在主模型上。
heavy-dirs-not-deniedinfo大型的 target/ 、 dist/ 、 build/ 、 coverage/ 、 .turbo/ 目录未被排除在读取之外。修复会添加 permissions.deny 规则。
large-lockfile-readableinfo超过 200 KB 的锁文件,模型可以完整打开。修复会添加一条 deny 规则。
instructions-longinfoCLAUDE.md 加上其 @imports 超过 200 行。按路径限定的 .claude/rules 和 skills 能降低成本;imports 不能。
compact-instructions-missinginfo没有 # Compact instructions 章节来引导摘要。
context-surfaceinfo每个会话都加载了大量 skills、plugins 或 MCP servers。
duplicate-skillsinfo同一个 skill 同时存在于用户级和项目级。
thinking-tokens-envinfoMAX_THINKING_TOKENS 在自适应推理模型上会被忽略。
prompt-cache-ttl-forced-shortinfoFORCE_PROMPT_CACHING_5M 会移除某些套餐享有的一小时缓存。
agent-teams-enabledinfoagent teams 会让每个队友成倍增加 token 用量。
mcp-output-limit-raisedinfo被调高的 MAX_MCP_OUTPUT_TOKENS 。
every-tool-hooksinfo匹配工具事件上 * 的 hooks(Pre/PostToolUse、PostToolUseFailure、PermissionRequest)会在每次调用时启动一个进程。这是延迟问题,不是 token 问题。修复会在试运行后移除它们;如果某个工具通过这些 hooks 显示代理状态,请先阅读警告。
idle-compaction-offinfoidleCompaction: false :长对话在其一小时缓存过期前不会被压缩。修复会取消该设置。
bash-output-raisedinfobashOutputMaxChars 或 BASH_MAX_OUTPUT_LENGTH 高于 30,000 默认值。
code-intelligence-missinginfo项目包含某种语言的文件,且该语言有官方 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 会对照当前文档检查它提到的每个设置键和变量。
FindingSeverityWhat it catches
late-compactionwarn超过 30% 的主线程成本花在上下文中超过 400K tokens 的情况下。
subagents-on-top-modelwarn子代理使用 Opus 或 Fable,产生超过全部成本 5% 的费用。分叉始终运行在主模型上。
long-sessionsinfo500+ 轮的会话,以及它们在成本中的占比。
idle-cache-rebuildsinfo提示缓存在中断期间过期后被重建。
images-read-repeatedlyinfo同一张图片被读取三次或更多次。
rereads-after-compactioninfo在摘要之前读取、并在接下来 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.1861141 s103–137 s
slide307/307$0.151(−19%)763 s(−33%)不到 1 s
evalkit(一个 eval harness,238 个测试),5 次和 3 次运行摘要238/238$0.149656 s约 50 s
slide238/238$0.096(−35%)472 s(−28%)不到 1 s
fixkit(12 个待找 bug,238 个测试),5 次运行摘要238/238$0.037154 s约 16 s
slide238/238$0.039(+6%)128 s(−17%)不到 1 s

更早、规模更小的 node bench/window.mjs 运行(60 个 300 行的文件逐个读取,然后在同一会话中做一次后续追问,200K 窗口)两种方式成本相同:

模型分支成本压缩次数回答正确
Haiku 5.5(3 次运行)摘要$0.58135/5
Haiku 5.5(3 次运行)slide 至 25%$0.5803.75/5
Sonnet 5.5(1 次运行)摘要$2.9335/5
Sonnet 5.5(1 次运行)slide 至 25%$2.9935/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。

许可证

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Hacker News
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗