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/tokendoctor
claude plugin install tokendoctor@tokendoctor

How 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

Other assistants

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.

Test level
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:sessions first: 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