Tokendoctor – the same Claude Code for up to 38% less
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 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:dashboard: 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@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 /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
] [--json] tokendoctor-sessions [--days
] [--project
] [--by day|week] [--json] tokendoctor-set --list |
|--unset [--scope user|project|local] [--write] tokendoctor-apply
[--scope user|project|local] [--project
] [--write] tokendoctor-undo [--json] |
[--write] tokendoctor-replay [--days
] [--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
] [--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. templates/statusline.sh is the status line script the fix installs into your Claude config folder. templates/agents/ holds three generic subagents (Explore, test-runner, docs-lookup), each pinned to a small model with read-only or narrow tools. A plugin cannot override a built-in agent or ship settings.json keys such as autoCompactWindow, env or permissions, so the apply step copies the template into ~/.claude/agents/ or .claude/agents/ and edits your settings files itself, with a backup. Claude Code changes every few days, so the audit does not trust a list frozen into the plugin: It reads the current settings reference and environment variable list from code.claude.com, as Markdown (every docs page is served at …/docs/en/
.md, indexed for models at llms.txt; a mirror such as context7 re-indexes on its own schedule). Cached a day in ~/.claude/tokendoctor/docs; --offline uses the cache only. Only those public pages are fetched; nothing is sent. It flags settings keys Claude Code does not document (settings-key-undocumented: a misspelled or removed key does nothing), variables of Claude Code's own families it does not know (env-undocumented), and keys that need a newer release than yours (setting-needs-newer-version). It reads a claude --debug log of the last day, if you have one, and tokendoctor-selfcheck makes one (one claude -p request on Haiku with no saved session; --log
reads one you have, at no cost): which copy of tokendoctor loaded and in which tier, whether the built-in guard was seated, the order of the mods on compaction, hooks that were skipped, the window Claude Code really compacts at, and a skill listing over its budget (descriptions cut short). The /tokendoctor:audit and /tokendoctor:optimize skills read a finding's doc page before they explain or recommend it. For whoever maintains tokendoctor, npm run docs:check checks every settings key and variable it names against the current docs. Off by default. With /tokendoctor slide on (or tokendoctor-set tokendoctor.slide true --write, or /tokendoctor:optimize), where Claude Code would compact, the plugin's hooks module elides old tool outputs into short pointers instead of summarizing, the way llx does. Every prompt, answer and decision stays word for word, and there is no summary pause. What goes first: reads made stale by a later read or edit of the same file, then what edits wrote (it is on disk), then the oldest outputs. The recent tail, outputs the model has not answered yet and Agent results stay. It frees down to tokendoctor.slideTo percent (default 25) of where Claude Code compacts, so slides are rare. Each one re-sends the context once, as a summary does; a pointer is never touched again. /compact still summarizes, and so does a slide that cannot free enough. Set a smaller window with autoCompactWindow (for example 400000) and the slide works from it. It takes idle compaction too (before the hour's cache expires); /compact and a plugin's $.session.compact still summarize. Team and Enterprise logins, and machines with managed settings. There Claude Code seats its built-in guard, cc-plugin-sec-default, ahead of the mods you install, and it sends compaction past them: the slide cannot run, and the audit and /tokendoctor slide say so. tokendoctor-org-install installs tokendoctor as the machine's own mod, which runs after the guard: a root-owned copy in the system folder and managed-settings.d/50-tokendoctor.json with appendPlugins (dry run first, then one sudo command; --uninstall undoes it). Where your organization delivers its own managed settings, files are ignored and only an administrator can add it. In one real session, at the same size: Claude Code's summary took 367K to 35K in 65.3 s; the slide took 368K to 36K in 0.04 s. Summaries in the author's real sessions take 79 s on average (109 of them, 22 September to 1 November). On bench/, Claude Code doing a TypeScript project against fixed acceptance tests, Haiku 5.5, a 100K window so that it compacts several times (medians). A short task with one compaction gains time but not money; the longer the work, the more the slide saves: The earlier, smaller runs of node bench/window.mjs (60 files of 300 lines read one by one, then a follow-up in the same session, 200K window) cost the same both ways: What a summary loses, measured with --task recall: the session starts with five decisions from the person, the files are deleted after reading, and the follow-up asks for the decisions and eight KEYs the model noted. Claude Code's summary kept them all: 6/6 and 8/8 in every run on both models. The slide did the same on Haiku 5.5 (3 runs, 2% dearer); on Sonnet 5.5 (1 run) it missed one KEY, which the model skipped noting in its first reply after a slide. So far no test shows the slide answering better, or worse: it saves time and money, not quality. It reads user, project and local settings files, ~/.claude.json (the MCP server names, to count them, and the plan type, to tell whether Claude Code's guard is seated), the managed settings files in the system folder and the cached server-managed ones (only to find the guard and its own machine copy), and your skill and agent folders. Managed settings it does not check against the rules. The audit fetches two public pages of Claude Code's docs once a day (--offline to skip); nothing else goes over the network, and nothing of yours is sent. Whether a rule helps depends on your plan and workload. Findings explain the trade-off and link to the documentation; decide for yourself. Deny rules in permissions.deny are best-effort for search tools and do not stop a read through Bash. Costs are dollars at each model's Claude API list price (lib/prices.mjs: cache reads at 0.05x input on Opus 5.5 and Sonnet 5.5, 0.025x on Fable 5.1, Haiku 5.5 priced by prompt length, fast mode, US-only inference, web search). On a Pro or Max plan that is what the same work would cost on the API: Anthropic does not publish how plan limits weigh each kind of token. Claude Code bills some requests it does not write into transcripts: a summary compaction's own request, titles, the small model that reads a page for WebFetch. Their cost is Claude Code's own session total (its cost-state lines) minus the responses in the transcripts, where that total holds; else the summaries are estimated from the context they read. Against the cost Claude Code reported on bench's 78 runs: equal to the cent on 77, 7.7% over on one. Sessions on other machines and transcripts Claude Code has already cleaned up are not counted, except for days already in the history file. 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 test/private.test.mjs fails if anything git would commit holds an API key or token, a home folder path or a temporary folder of the machine: benchmark results come from runs on someone's account, so only their summaries are committed and the transcripts stay local. The landing page lives in site/ (cd site && npm install && npm run dev; npm run build prerenders it, node scripts/og.mjs redraws the social card). The demo is a real session recorded with asciinema; site/scripts/RECORDING.md says how to record it again. Rules are pure functions over a snapshot (lib/rules.mjs); reading the disk lives in lib/collect.mjs and writing in lib/apply.mjs. Adding a rule means adding one entry and its test. Session analysis is in lib/sessions.mjs and lib/history.mjs, the settings tokendoctor-set may change in lib/tunables.mjs, the /tokendoctor command in lib/console.mjs, the replay in lib/replay.mjs, the slide in hooks/window.ts, and the optimize tools in hooks/register.ts. License MIT