Tokendoctor 让 Claude Code 成本最高降 38%
Tokendoctor 是一款本地运行的 Claude Code 成本诊断与优化工具,通过回放用户真实会话定位超额开销并给出可撤销的修复。作者基于六周真实使用测得主线程单请求成本下降 38%,单请求上下文从 412K 降至 219K,但效果高度依赖会话长度与模型配置。
报道正文
本文目录2 个章节
tokendoctor
The same Claude Code for up to 38% less
See what your Claude Code use overpays, fix it, undo it any time. Runs on your machine.
Website · Install · Changelog
| Measured on its author's six weeks of real use | |
|---|---|
| Main-thread cost per request at API list prices, the month before against the week after a 400K window and Sonnet for subagents | −38% |
| Context per request | 412K → 219K |
| The same sessions replayed at a 400K window: only the window changed | −33% of the main thread, −20% of all spend |
| The slide against a summary, the same day of work (bench) | −19% cost, −33% time |
| A week of work in bench (27 steps), Claude Code as it ships against every fix applied and the slide | −11 to −21% cost (medians of 2 and 3 runs; single runs −40% to +17%), all tests pass |
There is no one pill. If your sessions rarely pass 400K tokens, the window changes nothing for
you; a summary that lands just before you finish can cost more than it saves; your models, effort
and work all move the number. So tokendoctor shows you yours first: /tokendoctor:sessions replays
your own sessions at smaller windows before anything changes.
/tokendoctor : every token by day, model, effort, main thread and each subagent, context size and project. One local file; this is the author's own.
Install
claude plugin marketplace add localixai/tokendoctor
claude plugin install tokendoctor@tokendoctorUpdate with claude plugin marketplace update tokendoctor and claude plugin update tokendoctor@tokendoctor, then restart Claude Code. To try it without installing, clone the repository and run claude --plugin-dir /path/to/tokendoctor.
Use
| Command | What it does |
|---|---|
/tokendoctor:sessions [days] | What a smaller window would have saved you (your sessions replayed), then where tokens went over the last 30 days (or days), with findings. Read-only. |
/tokendoctor:audit | Setting checks by severity, each linked to the docs, a read of your memory and CLAUDE.md, then the usage dashboard. Read-only. |
/tokendoctor:dashboard [days] | Builds and opens a local dashboard of every session on this machine: spend by day, kind of token, model, reasoning effort, main thread and each subagent type, context size, project and hour, with filters. One HTML file, no network. |
/tokendoctor:optimize [focus] | Proposes up to five changes from your numbers and applies the ones you pick. |
/tokendoctor [name] [value] | Shows the main settings, explains one or changes it. No model call, no tokens. |
/tokendoctor fix <finding-id> | Applies one audit fix after showing it, with a backup of the file. |
/tokendoctor undo [n] | Lists the changes tokendoctor made, newest first, and puts change n back. |
/tokendoctor is answered by the plugin itself, so it costs nothing. Tab completes the names
(window, slide, cache, effort, model, subagents, and /tokendoctor all for the rest) and
their values; /tokendoctor window 400k applies as typed, /tokendoctor window reset goes back to the
default, --project or --local writes there instead of your user settings. A model name must be an
alias (opus, sonnet, haiku) or a claude-… id.
optimize changes only settings on the tunable list and /config rows. Every change opens a dialog that shows it and runs only on Apply; with no one to ask, as in a -p run, nothing changes. Hooks and permissions are never on the list.
The plugin's bin/ directory is on the Bash tool's PATH while it is enabled:
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)The skills are user-invoked only (disable-model-invocation). claude plugin details tokendoctor@tokendoctor estimates about 235 tokens of always-on cost for the five of them. The
plugin has no MCP server. Its hooks module adds the optimize tools (mcp__tokendoctor__*) behind
ToolSearch, so only their names are listed until /tokendoctor:optimize loads them. /tokendoctor
and the slide run in the hooks module too, with no model call, so they add no tokens. Its one command
hook runs tokendoctor-record in the background when a session starts. The hook is async and
prints nothing, so it adds no tokens. It appends each finished day's totals to
~/.claude/tokendoctor/history.jsonl, so the trend outlives Claude Code's transcript cleanup.
Errors are settings that are wrong or ignored, warnings are likely to cost real money, and info is worth a look. Rules that depend on a Claude Code release are skipped on older versions.
| Finding | Severity | What it catches | | ---
(注:更多技术实现细节与完整 API 文档请查阅原项目 README)