Home / Blog / Tokendoctor – the same Claude Code for up to 38% less
Tech News

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

Tokendoctor – the same Claude Code for up to 38% less
Image: 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

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.

MeasureBeforeAfter
Main-thread cost per requestMonth before, at API list pricesWeek after a 400K window and Sonnet for subagents: −38%
Context per request412K219K
Same sessions, window onlySessions unchanged, only the window changed−33% of the main thread, −20% of all spend
Slide against a summarySame day of work in the bench−19% cost, −33% time
27-step week of workClaude Code as it shipsEvery 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.

  1. Add the marketplace Run claude plugin marketplace add localixai/tokendoctor.
  2. Install the plugin Run claude plugin install tokendoctor@tokendoctor.
  3. Update and restart Run claude plugin marketplace update tokendoctor and claude plugin update tokendoctor@tokendoctor, then restart Claude Code.
Command
claude plugin marketplace add localixai/tokendoctor
claude plugin install tokendoctor@tokendoctor
Command
claude plugin marketplace update tokendoctor
claude plugin update tokendoctor@tokendoctor
Command
claude --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.

Command
/tokendoctor window 400k
/tokendoctor window reset
/tokendoctor slide on
/tokendoctor model sonnet

Optimize 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.

Command
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.

FindingSeverityWhat it catches
settings-unreadableerrorA settings file that exists but is not valid JSON, so nothing in it applies.
compact-threshold-undocumentederrorautoCompactThreshold is not a Claude Code setting; the real key is autoCompactWindow. Fix removes it.
compact-env-bare-numbererrorCLAUDE_CODE_AUTO_COMPACT_WINDOW below 100,000 (a bare number is tokens, not thousands).
compact-window-unsetwarnModels with a native 1M window compact only near 967K by default. Fix sets 400,000.
compact-window-smallwarnA window so small that frequent compaction breaks the prompt cache.
prompt-caching-disabledwarnA DISABLE_PROMPT_CACHING* variable is set.
subagent-model-forcewarnEvery subagent, including reasoning ones, is forced onto one model.
effort-max-in-settingswarneffortLevel: "max" is not accepted in settings. Fix uses xhigh.
advisor-inactivewarnAn advisor that will silently not run (telemetry or feature-flag fetching off, advisor below the main model, tool disabled).
fast-mode-enabledwarnfastMode: true saved as a default, so every session pays the higher fast-mode rate. Fix sets fastModePerSessionOptIn.
auto-compact-offwarnDISABLE_AUTO_COMPACT or autoCompactEnabled: false: history grows until the model window fills. Fix unsets the setting.
tool-search-offwarn/infoENABLE_TOOL_SEARCH=false loads every MCP tool definition into every request.
explore-default-modelinfoThe built-in Explore agent runs on Opus on many accounts. Fix installs a Haiku, read-only override.
subagent-model-unsetinfoGeneral-purpose subagents inherit an expensive main model. Fix sets CLAUDE_CODE_SUBAGENT_MODEL=sonnet.
main-model-expensiveinfoOpus or Fable as the default; suggests Sonnet.
agents-inherit-modelinfoCustom agents with no model run on the main model.
heavy-dirs-not-deniedinfoLarge target/, dist/, build/, coverage/, .turbo/ directories not excluded from reads. Fix adds permissions.deny rules.
large-lockfile-readableinfoLockfiles over 200 KB that a model can open in full. Fix adds a deny rule.
instructions-longinfoCLAUDE.md plus its @imports over 200 lines. Path-scoped .claude/rules and skills cut the cost; imports do not.
compact-instructions-missinginfoNo # Compact instructions section to steer summaries.
context-surfaceinfoMany skills, plugins or MCP servers loaded in every session.
duplicate-skillsinfoThe same skill at user and project level.
thinking-tokens-envinfoMAX_THINKING_TOKENS is ignored on adaptive-reasoning models.
prompt-cache-ttl-forced-shortinfoFORCE_PROMPT_CACHING_5M removes the one-hour cache some plans get.
agent-teams-enabledinfoAgent teams multiply token use per teammate.
mcp-output-limit-raisedinfoA raised MAX_MCP_OUTPUT_TOKENS.
every-tool-hooksinfoHooks 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-offinfoidleCompaction: false: a long conversation is not compacted before its one-hour cache expires. Fix unsets it.
bash-output-raisedinfobashOutputMaxChars or BASH_MAX_OUTPUT_LENGTH above the 30,000 default.
code-intelligence-missinginfoThe 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-undocumentedwarnA 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

Dillip Chowdary

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

5-min tech signal

Weekday briefing for engineers who skip the noise.

No spam · Unsubscribe anytime

Advertisement

✈️ CareerPilot

Your AI job-search copilot

Match your resume against live Ashby, Greenhouse & Lever openings — fit scores, job-specific resume optimization and email alerts.

Find matching jobs →

Free Tools

Browse all tools →