ALL INTELLIGENCE
Hacker News AIT2·Tools

Tokendoctor Cuts Claude Code Costs by Up to 38 Percent

Original title: Tokendoctor – the same Claude Code for up to 38% less
58AI Score

Tokendoctor is a locally run cost-diagnostics and optimization tool for Claude Code that replays a user's real sessions to surface overspend and apply reversible fixes. On the author's six weeks of actual use it cut main-thread cost per request by 38% and context per request from 412K to 219K, though gains depend heavily on session length and model configuration.

Full Report

Contents2 sections

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 request412K → 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.

<table> <tr> <td width="25%" valign="top"> <strong>See</strong><br> <code>/tokendoctor:sessions</code> replays your own sessions at smaller windows and says what each would have saved, then where the tokens went. </td> <td width="25%" valign="top"> <strong>Fix</strong><br> <code>/tokendoctor:optimize</code> runs 38 checks against the docs and applies the changes you pick, each shown as a diff first. </td> <td width="25%" valign="top"> <strong>Slide</strong><br> <code>/tokendoctor slide on</code>: where Claude Code would summarize, old tool outputs go instead. No pause, the conversation stays word for word. </td> <td width="25%" valign="top"> <strong>Undo</strong><br> <code>/tokendoctor undo</code> lists every change tokendoctor made and puts any one back. No model call, no tokens. </td> </tr> </table>

/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

BASH
claude plugin marketplace add localixai/tokendoctor
claude plugin install tokendoctor@tokendoctor

Update 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

CommandWhat 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:auditSetting 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.

<details> <summary><strong>From a shell</strong></summary>

The plugin's bin/ directory is on the Bash tool's PATH while it is enabled:

BASH
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)
</details> <details> <summary><strong>What it costs to keep installed</strong></summary>

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.

</details> <details> <summary><strong>The 38 setting checks</strong></summary>

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)