Tokendoctor – the same Claude Code for up to 38% less
Tokendoctor, a local Claude Code plugin, cut its author's main-thread cost per request 38% at API list prices after a 400K window and Sonnet for subagents.
By Dillip Chowdary • Nov 17, 2026 • Source: github.com

At a glance
- Product
- Tokendoctor
- Platform
- Claude Code on your machine
- Savings
- 38% main-thread cost per request
- Context
- 412K down to 219K
- Overhead
- About 235 tokens for five skills
- Audit
- 38 checks against the docs
In this post
The sessions paragraph is two words over the limit, and the deck is short of 145 characters.Tokendoctor is a local Claude Code plugin for the same Claude Code at up to 38 percent less. It shows where your use overpays, applies the fixes you pick, and undoes any of them later. On its author's six weeks of real use, main-thread cost per request at API list prices fell 38 percent in the week after a 400K window and Sonnet for subagents, versus the month before, according to github.com's report.
This piece covers sessions, optimize, slide, undo, the install and shell commands, the always-on token cost, and the setting checks. It is for Claude Code users who want their own sessions replayed before they apply a smaller window, a subagent model, or a slide.
01Author six-week list-price cut
The published comparison is main-thread cost per request at API list prices, the month before against the week after a 400K window and Sonnet for subagents. Context per request on that stretch moved from 412K to 219K. Three benches then separate the window, the slide, and every fix together.
Replaying the same sessions at a 400K window, and changing only the window, cut 33 percent of the main thread and 20 percent of all spend. The slide against a summary, on the same day of work, cut 19 percent of cost and 33 percent of time. A 27-step week of work compared Claude Code as it ships against every fix applied and the slide.
02Bench medians and context size
The 27-step week is not a single score. Medians of two and three runs landed between an 11 percent and a 21 percent cost cut, while single runs ranged from a 40 percent cut to a 17 percent increase, and all tests passed.
Note: 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:sessions replays your own sessions at smaller windows before anything changes.
| Measure | Before | After |
|---|---|---|
| Main-thread cost per request | Month before, at API list prices | Week after a 400K window and Sonnet for subagents: −38% |
| Context per request | 412K | 219K |
| Same sessions, window only | Sessions unchanged, only the window changed | −33% of the main thread, −20% of all spend |
| Slide against a summary | Same day of work in the bench | −19% cost, −33% time |
| 27-step week of work | Claude Code as it ships | Every fix plus the slide: −11% to −21% cost (medians of 2 and 3 runs); single runs −40% to +17%; all tests pass |
03Sessions, slide, undo, dashboard
/tokendoctor:sessions [days] replays sessions at a smaller window, says what each would have saved, then where tokens went over the last 30 days or the day count you pass, with findings, and it is read-only. /tokendoctor:audit lists setting checks by severity, each linked to the docs, reads memory and CLAUDE.md, then opens the usage dashboard, and it is read-only. /tokendoctor:optimize runs 38 checks against the docs, shows each picked change as a diff first, and proposes up to five changes from your numbers.
/tokendoctor slide on puts old tool outputs where Claude Code would summarize. There is no pause, and the conversation stays word for word. /tokendoctor undo lists every change tokendoctor made and puts any one back, with no model call and no tokens, and /tokendoctor undo [n] lists those changes newest first and puts change n back.
/tokendoctor:dashboard records every token by day, model, effort, main thread, and each subagent, plus context size and project, in one local file of the author's own. /tokendoctor:dashboard [days] builds and opens a local dashboard of every session on this machine, with spend by day, kind of token, model, reasoning effort, main thread and each subagent type, context size, project, and hour, with filters. It is one HTML file and uses no network.
Advertisement
Tech Pulse Daily
Get tomorrow's pulse first
Join engineers who read Tech Pulse before stand-up. Free, weekday mornings.
04Marketplace install and slash commands
Installing tokendoctor takes two plugin commands, and updating it takes two more plus a restart of Claude Code. The add command names the marketplace localixai/tokendoctor, the install and update commands name the plugin tokendoctor@tokendoctor, and the marketplace update command names tokendoctor. To try it without installing, clone the repository and launch Claude Code with --plugin-dir set to that checkout.
- Add the marketplace Run claude plugin marketplace add localixai/tokendoctor.
- Install the plugin Run claude plugin install tokendoctor@tokendoctor.
- Update and restart Run claude plugin marketplace update tokendoctor and claude plugin update tokendoctor@tokendoctor, then restart Claude Code.
claude plugin marketplace add localixai/tokendoctor
claude plugin install tokendoctor@tokendoctorclaude plugin marketplace update tokendoctor
claude plugin update tokendoctor@tokendoctorclaude --plugin-dir /path/to/tokendoctor/tokendoctor shows the main settings or changes one setting, and the plugin answers it with no model call and no tokens. Tab completion fills window, slide, cache, effort, model, subagents, and /tokendoctor all, /tokendoctor window 400k applies as typed, /tokendoctor window reset returns the default, and --project or --local writes there instead of user settings. A model value must be opus, sonnet, haiku, or a claude- id, and /tokendoctor fix plus a finding id applies that audit fix after showing it, with a file backup.
/tokendoctor window 400k
/tokendoctor window reset
/tokendoctor slide on
/tokendoctor model sonnetOptimize changes only settings on the tunable list and /config rows, every change opens a dialog and runs only on Apply, and a -p run with no one to ask changes nothing because hooks and permissions are never on that list. While the plugin is enabled, its bin directory is on the Bash tool's PATH. From that shell, tokendoctor-audit, tokendoctor-sessions, tokendoctor-set, tokendoctor-apply, tokendoctor-undo, tokendoctor-replay, tokendoctor-org-install, and tokendoctor-selfcheck are the shipped binaries.
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]
# what a smaller window would have saved
tokendoctor-replay [--days <n>] [--window 200k,400k] [--json]
# the slide under a Team/Enterprise login
tokendoctor-org-install [--write] [--uninstall]
# what really loaded, from a debug log (one small Haiku request, or a log you have)
tokendoctor-selfcheck [--log <file>] [--json]05Always-on tokens and setting checks
The skills are user-invoked only, with disable-model-invocation, and claude plugin details tokendoctor@tokendoctor estimates about 235 tokens of always-on cost for the five of them. The plugin has no MCP server, and its hooks module adds the optimize tools, named mcptokendoctor*, behind ToolSearch, so only their names are listed until /tokendoctor:optimize loads them. /tokendoctor and the slide also run in that hooks module with no model call, so they add no tokens.
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, and 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, info is worth a look, and 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 (PreToolUse, 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 ref. |
Frequently asked questions
How much did the author's Claude Code spend fall?
Main-thread cost per request at API list prices fell 38 percent in the week after a 400K window and Sonnet for subagents, compared with the month before. Context per request moved from 412K to 219K. Replaying the same sessions with only the window changed cut 33 percent of the main thread and 20 percent of all spend.
When does a 400K window save nothing?
If sessions rarely pass 400K tokens, the window changes nothing. A summary that lands just before you finish can cost more than it saves. /tokendoctor:sessions replays your own sessions at smaller windows before anything changes.
How do you install and update the tokendoctor plugin?
Run claude plugin marketplace add localixai/tokendoctor, then 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.
How many tokens does tokendoctor add while it is installed?
claude plugin details tokendoctor@tokendoctor estimates about 235 tokens of always-on cost for the five skills, which are user-invoked only (disable-model-invocation). The plugin has no MCP server. /tokendoctor, the slide, and the async tokendoctor-record hook make no model call, so they add no tokens.
How do you undo a change tokendoctor made?
/tokendoctor undo lists every change tokendoctor made, newest first, and /tokendoctor undo with a number puts that change back. The command uses no model call and no tokens. From the shell, tokendoctor-undo does the same job.
Sources
Author
Dillip Chowdary
Writes Tech Bytes coverage of AI, engineering, and the tools that actually ship. Editor of Tech Pulse Daily.
Related on Tech Bytes
Advertisement