PluginPartly tested (needs an account)
Find out where your Claude tokens go
tokendoctor
Free MIT plugin that checks your Claude Code settings and past sessions for waste, explains each finding and applies only the fixes you pick, with undo.
- Works with
- Claude Code
- Good for
- Everyone
What it does
tokendoctor helps you understand why Claude Code uses up your plan or your API budget. It reads your own past sessions on your computer and shows where the tokens went: very long conversations, sub-agents on the most expensive model, or settings that load more than you need.
It also runs 31 setting checks, each linked to the official docs, and explains the trade-off of every fix. When you choose a fix, it shows the change first, applies it only when you click Apply and keeps a backup.
/tokendoctor undo lists every change it made and puts any one back. The /tokendoctor command itself answers without a model call, so it uses no tokens.
An optional slide mode trims old tool output instead of summarising a long conversation. It is off by default.
Example prompts
- "/tokendoctor:sessions 30"
- "/tokendoctor:audit"
- "/tokendoctor:optimize"
- "/tokendoctor undo"
How to install
claude plugin marketplace add rsaryev/tokendoctorclaude plugin install tokendoctor@tokendoctorHow to use it
Run /tokendoctor:sessions to see where your tokens went, /tokendoctor:audit for a read-only settings check, then /tokendoctor:optimize to pick fixes.
Check it works
Restart Claude Code after installing and type /tokendoctor. It should list your main settings without calling a model.
Common problems
- The commands do not appear — restart Claude Code after installing or updating the plugin — https://github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/README.md
- Organisation settings are not checked — it cannot see managed settings set by your company — https://github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/README.md
- Session reports look incomplete — sessions from other computers and transcripts Claude Code already cleaned up are not counted — https://github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/README.md
- The status line fix does nothing — the installed status line script needs
jq— https://github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/README.md
Other assistants
- Codex: not supported; it is a Claude Code plugin only — https://github.com/rsaryev/tokendoctor
- Gemini CLI: not supported, and not in the Gemini CLI extensions gallery — https://geminicli.com/extensions/
What to watch out for
- Reads your saved session transcripts from all projects (~/.claude/projects/*/*.jsonl, sub-agents included), your user, project and local settings files, ~/.claude.json (only the MCP server names, to count them) and your skill and agent folders. No network calls were found in the code; reports are made on your computer
- Adds a SessionStart hook that runs node bin/tokendoctor-record in the background at each new session and appends daily token totals to ~/.claude/tokendoctor/history.jsonl. It also adds a Claude Code mod (hooks/register.ts) with the /tokendoctor command and five mcp__tokendoctor__* tools for /tokendoctor:optimize, and puts its bin/ scripts on the Bash tool's PATH while the plugin is on
- A fix you apply edits your Claude Code settings files and can copy agent files into ~/.claude/agents/ (for example a Haiku override of the built-in Explore agent) or install a status line script that needs jq. Each change is shown first, runs only on Apply, keeps a backup and is listed in ~/.claude/tokendoctor/changes.jsonl for /tokendoctor undo
- The optional slide mode (off by default) changes what the model sees when Claude Code would compact: old tool outputs become short pointers, images and thinking are dropped, and when that is not enough the code (hooks/window.ts) removes the oldest turns whole. The README says every prompt and answer stays word for word, which does not cover that last case
- The savings figures in the README (for example up to 40% less) are the author's own measurements on his own use. Session reports show shares of cost, not dollars; your results depend on your plan, models and how you work
Licence and author
- Licence
- MIT
- Author
- rsaryev
- Source code
- github.com/rsaryev/tokendoctor
How we tested it
We installed it on an empty test computer on 3 Nov 2026. Partly tested: installed in a clean test system, but its main features need an account or key we did not use.
Technical details of the test
- Date
- 3 Nov 2026
- Method
- Reviewed by our team against the repository, its README and docs.
Checked again on 3 Nov 2026
Alternatives
- Session Report — Anthropic's report on where your Claude Code usage goes, without the setting fixes
- receipts — a report on what Claude Code did for you
- Claude Code Setup — setup tips for your project, without the cost checks
FAQ
- Q: Will it change things without asking? A: No. Every change opens a dialog and runs only on Apply; in a run with no one to ask (
claude -p), nothing changes. Hooks and permissions are never on its list of settings to change. - Q: Does it send my sessions anywhere? A: No network code was found. It reads your local files and builds the reports on your computer.
- Q: Does it cost tokens to keep installed? A: The README estimates about 160 tokens of always-on cost for its four skills.
- Q: How much will I save? A: Nobody can say in advance. Run
/tokendoctor:sessionsfirst: it replays your own sessions and shows what a change would have done for you.
Sources
- github.com/rsaryev/tokendoctor
- github.com/rsaryev/tokendoctor/tree/f416dd5afa0e8b48eb1b7acc328504dfad315f97
- github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/README.md
- github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/hooks/hooks.json
- github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/hooks/register.ts
- github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/hooks/window.ts
- github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/lib/sessions.mjs
- github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/lib/collect.mjs
- github.com/rsaryev/tokendoctor/blob/f416dd5afa0e8b48eb1b7acc328504dfad315f97/CHANGELOG.md
- code.claude.com/docs/en/plugins/mods/overview