tokendoctor plugin
tokendoctor shows where Claude Code overpays in tokens, proposes settings fixes and rolls them back with one command
- 70 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The plugin reads your session history and Claude Code settings, and the `optimize` skill rewrites settings files
- A session start hook appends daily totals to `~/.claude/tokendoctor/history.jsonl` in the background
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/tokendoctorDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The plugin reads your session history and Claude Code settings, and the `optimize` skill rewrites settings files
- A session start hook appends daily totals to `~/.claude/tokendoctor/history.jsonl` in the background
This is third-party code. Review the repository files before installing.
What it does
The plugin inspects your Claude Code settings and session history. The `audit` skill checks the configuration against the current docs at code.claude.com and returns errors, warnings and notes with a cost estimate. The `sessions` skill shows spending by day or week, and `tokendoctor-replay` replays your past sessions with a smaller context window and shows what that would have saved. Fixes come from the `optimize` skill: every change appears in a dialog and runs only after Apply. It can change the auto-compact window, cache, effort level, model and subagents, and hooks and permissions are not on the list. A backup is made before writing and `tokendoctor-undo` reverts. `/tokendoctor` answers without a model call, so it spends no tokens. The plugin `bin/` folder lands on the Bash tool PATH.
Who it is for. People who use Claude Code every day and want to see the real causes of a big token bill and safely tune their settings.
Good fit when
- The token bill grows and it is unclear whether the context window, the model or subagents are to blame
- You need to check which Claude Code settings are ignored or mistyped
- Before changing the auto-compact window you want a calculation on your own sessions
- Sessions rarely pass 400K tokens and you must see whether a big window helps them
- Under a Team or Enterprise login you need the summary slide through `tokendoctor-org-install`
Not a fit when
- You need edits to hooks and permissions: the tool does not change them
- You work outside Claude Code, because the plugin is built for it only
- You need to compress command output on the fly, which separate token optimizers do
Example request
Run a tokendoctor audit and show how much I would have saved on a 400k window from past sessionsLimitations
Audit rules depend on the Claude Code release and some are skipped on older versions. The author warns that there is no single cure: with rare long sessions the window gives nothing, and a summary just before you finish can cost more than it saves. The tool reads the current docs from code.claude.com and caches them for a day. A helper hook appends each day's totals to `~/.claude/tokendoctor/history.jsonl`. `selfcheck` makes one small-model request.
How to disable. Run `claude plugin uninstall tokendoctor@tokendoctor`. Applied changes revert with `tokendoctor-undo`, and the history goes away by deleting `~/.claude/tokendoctor/history.jsonl`.
FAQ
How do I install tokendoctor?
Run `claude plugin marketplace add rsaryev/tokendoctor` and `claude plugin install tokendoctor@tokendoctor`, then restart Claude Code. To try it without installing use `claude --plugin-dir`.
Can it break anything?
Changes apply only after confirmation in a dialog, a backup is made before writing and `tokendoctor-undo` restores the earlier settings. The tool does not touch hooks or permissions.
How many tokens does the plugin itself use?
By the `claude plugin details` estimate, about 160 tokens of always-on cost for the four skills. `/tokendoctor` answers without a model call.
What is replay?
`tokendoctor-replay` recomputes your past sessions with windows such as 200k and 400k and shows what would change in spending.
How is it different from token optimizers?
It examines settings and session history and proposes configuration fixes. Optimizers such as token-optimizer compress context or command output while you work.
Discussion
No questions or reviews yet.
Related
PluginsA Claude Code plugin that replaces built-in file tools with lighter versions so a session spends fewer tokens
A local dashboard for Claude Code sessions: timelines, token costs, tools, agents, skills and live sessions
An installer for a set of hooks, commands and plugins that compress tool output and save tokens in Claude Code.
A CLI installer for eight token-saving tools: rules, hooks, MCP servers and a local proxy for Claude Code, Codex and Cursor.
A local proxy with a terminal dashboard: shows how many tokens each Claude Code and Codex request sends and saves the prompts to files
A local proxy and plugin for Claude Code and Codex that trims tool output, keeps the prompt cache warm and shows the savings
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| tokendoctor (this card) | no | 70 | |
| Token Optimizer | no | 2,964 | compresses context and output while you work, while tokendoctor reviews settings and session history |
| Claude Token Optimizer: fewer tokens at startup | no | 653 | a standalone optimization CLI, while tokendoctor is a plugin inside Claude Code with rollback |
README in short
The README starts from the idea that no single saving trick exists and shows how to check your own sessions before changes. It then covers install, commands and the four skills, the `bin/` utilities, audit rules drawn from the docs and the spending model. Notes on hooks and the license close the page.