localixai/tokendoctor
localixai/tokendoctor has 71 GitHub stars and 7 forks. GitHot measured +20 in 7 days and +58 in 15 days. Last checked 2026-11-15 22:14 UTC. Last push 2026-11-13.
Measured star growth
- in 24h
- Update delayed
- in 7 days
- +20
- in 15 days
- +58
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
tokendoctor: the same Claude Code for up to 38% less. A Claude Code plugin that shows what your use overpays, fixes it with a diff you approve, and puts any change back. Runs on your machine.
Developer ToolsREADME.md
Original
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.
| 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.
See/tokendoctor:sessions replays your own sessions at smaller windows and says what each would have saved, then where the tokens went.
|
Fix/tokendoctor:optimize runs 38 checks against the docs and applies the changes you pick, each shown as a diff first.
|
Slide/tokendoctor slide on: where Claude Code would summarize, old tool outputs go instead. No pause, the conversation stays word for word.
|
Undo/tokendoctor undo lists every change tokendoctor made and puts any one back. No model call, no tokens.
|

/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
| 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.
From a shell
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)
What it costs to keep installed
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.
The 38 setting checks
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 |
|---|---|---|
settings-unreadable |
error | A settings file that exists but is not valid JSON, so nothing in it applies. |
compact-threshold-undocumented |
error | autoCompactThreshold is not a Claude Code setting; the real key is autoCompactWindow. Fix removes it. |
compact-env-bare-number |
error | CLAUDE_CODE_AUTO_COMPACT_WINDOW below 100,000 (a bare number is tokens, not thousands). |
compact-window-unset |
warn | Models with a native 1M window compact only near 967K by default. Fix sets 400,000. |
compact-window-small |
warn | A window so small that frequent compaction breaks the prompt cache. |
prompt-caching-disabled |
warn | A DISABLE_PROMPT_CACHING* variable is set. |
subagent-model-force |
warn | Every subagent, including reasoning ones, is forced onto one model. |
effort-max-in-settings |
warn | effortLevel: "max" is not accepted in settings. Fix uses xhigh. |
advisor-inactive |
warn | An advisor that will silently not run (telemetry or feature-flag fetching off, advisor below the main model, tool disabled). |
fast-mode-enabled |
warn | fastMode: true saved as a default, so every session pays the higher fast-mode rate. Fix sets fastModePerSessionOptIn. |
auto-compact-off |
warn | DISABLE_AUTO_COMPACT or autoCompactEnabled: false: history grows until the model window fills. Fix unsets the setting. |
tool-search-off |
warn/info | ENABLE_TOOL_SEARCH=false loads every MCP tool definition into every request. |
explore-default-model |
info | The built-in Explore agent runs on Opus on many accounts. Fix installs a Haiku, read-only override. |
subagent-model-unset |
info | General-purpose subagents inherit an expensive main model. Fix sets CLAUDE_CODE_SUBAGENT_MODEL=sonnet. |
main-model-expensive |
info | Opus or Fable as the default; suggests Sonnet. |
agents-inherit-model |
info | Custom agents with no model run on the main model. |
heavy-dirs-not-denied |
info | Large target/, dist/, build/, coverage/, .turbo/ directories not excluded from reads. Fix adds permissions.deny rules. |
large-lockfile-readable |
info | Lockfiles over 200 KB that a model can open in full. Fix adds a deny rule. |
instructions-long |
info | CLAUDE.md plus its @imports over 200 lines. Path-scoped .claude/rules and skills cut the cost; imports do not. |
compact-instructions-missing |
info | No # Compact instructions section to steer summaries. |
context-surface |
info | Many skills, plugins or MCP servers loaded in every session. |
duplicate-skills |
info | The same skill at user and project level. |
thinking-tokens-env |
info | MAX_THINKING_TOKENS is ignored on adaptive-reasoning models. |
prompt-cache-ttl-forced-short |
info | FORCE_PROMPT_CACHING_5M removes the one-hour cache some plans get. |
agent-teams-enabled |
info | Agent teams multiply token use per teammate. |
mcp-output-limit-raised |
info | A raised MAX_MCP_OUTPUT_TOKENS. |
every-tool-hooks |
info | Hooks matching * on a tool event (Pre/PostToolUse, PostToolUseFailure, PermissionRequest) start a process per call. Latency, not tokens. Fix drops them after a dry run; read the warning first if a tool shows agent status from them. |
idle-compaction-off |
info | idleCompaction: false: a long conversation is not compacted before its one-hour cache expires. Fix unsets it. |
bash-output-raised |
info | bashOutputMaxChars or BASH_MAX_OUTPUT_LENGTH above the 30,000 default. |
code-intelligence-missing |
info | The project has files for a language with an official language-server plugin (typescript-lsp, pyright-lsp, gopls-lsp, …) and it is not enabled. |
settings-key-undocumented |
warn | A settings key that is not in today's settings reference: misspelled or removed, so it does nothing. |
env-undocumented |
info | A CLAUDE_…/ANTHROPIC_…-style variable under env that today's docs do not list. |
setting-needs-newer-version |
warn | A key or variable the docs say needs a newer Claude Code than the one installed. |
slide-blocked-by-guard |
warn | The slide is on, but Claude Code's built-in guard sends compaction past the mods you install (a Team or Enterprise login, or managed settings), so it summarizes instead. Says to run tokendoctor-org-install. |
compact-pct-override |
info/warn/error | CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: where it puts the compaction point; a warning below 50%, an error when it is not a percent. |
skill-model-switch |
info | A skill whose frontmatter names another model: each use reads the conversation uncached on that model. context: fork avoids it. |
opusplan-cache |
info | opusplan switches models, and so caches, on every plan-mode toggle. |
no-statusline |
info | No status line. Fix installs tokendoctor-statusline.sh and points statusLine at it (needs jq). One quiet line: Opus 5.5 · api main* · 120k/367k · cache 1h · 5h 51% · week 35% · $24. Tokens are shown against the point where Claude Code compacts; cache 1h is how long the prompt cache stays warm; a limit adds → 100% in 48m only when, at the recent pace (5h: the last hour, week: the last day), it runs out before it resets. The finding also mentions the token-weather mod from anthropics/claude-code-playground as an alternative (needs Claude Code 2.1.287+, shared as-is). |
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.
Checked against today's docs and what really loaded
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/<page>.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;--offlineuses 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 --debuglog of the last day, if you have one, andtokendoctor-selfcheckmakes one (oneclaude -prequest on Haiku with no saved session;--log <file>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:auditand/tokendoctor:optimizeskills read a finding's doc page before they explain or recommend it. - For whoever maintains tokendoctor,
npm run docs:checkchecks every settings key and variable it names against the current docs.
What the session report finds
| Finding | Severity | What it catches |
|---|---|---|
late-compaction |
warn | Over 30% of main-thread cost spent with more than 400K tokens in context. |
subagents-on-top-model |
warn | Subagents on Opus or Fable making over 5% of all cost. Forks always run on the main model. |
long-sessions |
info | Sessions of 500+ turns, with their share of cost. |
idle-cache-rebuilds |
info | The prompt cache rebuilt after it expired during a break. |
images-read-repeatedly |
info | The same image read three or more times. |
rereads-after-compaction |
info | Files read before a summary and read again within the next 10 requests: what the summary lost. Shown against slides when there are some. |
Slide the window instead of compacting
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.slideTopercent (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. /compactstill summarizes, and so does a slide that cannot free enough. Set a smaller window withautoCompactWindow(for example 400000) and the slide works from it.- It takes idle compaction too (before the hour's cache expires);
/compactand a plugin's$.session.compactstill 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 slidesay so.tokendoctor-org-installinstalls tokendoctor as the machine's own mod, which runs after the guard: a root-owned copy in the system folder andmanaged-settings.d/50-tokendoctor.jsonwithappendPlugins(dry run first, then onesudocommand;--uninstallundoes 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:
| Task | Arm | Tests passed | Cost | Time | Waiting on compactions |
|---|---|---|---|---|---|
| a day of work (7 requests, 307 tests), 2 runs | summary | 307/307 | $0.186 | 1141 s | 103–137 s |
| slide | 307/307 | $0.151 (−19%) | 763 s (−33%) | under 1 s | |
| evalkit (an eval harness, 238 tests), 5 and 3 runs | summary | 238/238 | $0.149 | 656 s | about 50 s |
| slide | 238/238 | $0.096 (−35%) | 472 s (−28%) | under 1 s | |
| fixkit (12 bugs to find, 238 tests), 5 runs | summary | 238/238 | $0.037 | 154 s | about 16 s |
| slide | 238/238 | $0.039 (+6%) | 128 s (−17%) | under 1 s |
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:
| Model | Arm | Cost | Compactions | Answers right |
|---|---|---|---|---|
| Haiku 5.5 (3 runs) | summary | $0.581 | 3 | 5/5 |
| Haiku 5.5 (3 runs) | slide to 25% | $0.580 | 3.7 | 5/5 |
| Sonnet 5.5 (1 run) | summary | $2.93 | 3 | 5/5 |
| Sonnet 5.5 (1 run) | slide to 25% | $2.99 | 3 | 5/5 |
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.
Limits
- 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 (
--offlineto 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.denyare 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-statelines) 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.
Develop
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