Maintainer of this skill?
by rsaryev
Claude Code plugin: see where your tokens go, audit your setup against the docs, and tune settings with an approved diff
# Add to your Claude Code skills
git clone https://github.com/rsaryev/tokendoctorSee how tokendoctor compares with popular alternatives.
tokendoctor is an open-source documentation skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by rsaryev. Claude Code plugin: see where your tokens go, audit your setup against the docs, and tune settings with an approved diff. It has 50 GitHub stars.
tokendoctor's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/rsaryev/tokendoctor" and add it to your Claude Code skills directory (see the Installation section above).
tokendoctor is primarily written in TypeScript. It is open-source under rsaryev on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other Documentation skills you can browse and compare side by side. Open the Documentation category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh tokendoctor against similar tools.
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
Available after the catalog security scan passes.
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
| Measured on its author's six weeks of real use | |
|---|---|
| Main-thread cost per request at API list prices, the month before against the week after a 400K window and Sonnet for subagents | −38% |
| Context per request | 412K → 219K |
| The same sessions replayed at a 400K window: only the window changed | −33% of the main thread, −20% of all spend |
| The slide against a summary, the same day of work (bench) | −19% cost, −33% time |
| A week of work in bench (27 steps), Claude Code as it ships against every fix applied and the slide | −11 to −21% cost (medians of 2 and 3 runs; single runs −40% to +17%), all tests pass |
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 shows you yours first: /tokendoctor:sessions replays
your own sessions at smaller windows before anything changes.
claude plugin marketplace add rsaryev/tokendoctor
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.
| Command | What it does |
|---|---|
/tokendoctor:sessions [days] |
What a smaller window would have saved you (your sessions replayed), then where tokens went over the last 30 days (or days), with findings. Read-only. |
/tokendoctor:audit |
Setting checks by severity, each linked to the docs, a read of your memory and CLAUDE.md, then the usage dashboard. Read-only. |
/tokendoctor:dashboard [days] |
Builds and opens a local dashboard of every session on this machine: spend by day, kind of token, model, reasoning effort, main thread and each subagent type, context size, project and hour, with filters. One HTML file, no network. |
/tokendoctor:optimize [focus] |
Proposes up to five changes from your numbers and applies the ones you pick. |
/tokendoctor [name] [value] |
Shows the main settings, explains one or changes it. No model call, no tokens. |
/tokendoctor fix <finding-id> |
Applies one audit fix after showing it, with a backup of the file. |
/tokendoctor undo [n] |
Lists the changes tokendoctor made, newest first, and puts change n back. |
/tokendoctor is answered by the plugin itself, so it costs nothing. Tab completes the names
(window, slide, cache, effort, model, subagents, and /tokendoctor all for the rest) and
their values; /tokendoctor window 400k applies as typed, /tokendoctor window reset goes back to the
default, --project or --local writes there instead of your user settings. A model name must be an
alias (opus, sonnet, haiku) or a claude-… id.
optimize changes only settings on the tunable list and /config rows. Every change opens a dialog that shows it and runs only on Apply; with no one to ask, as in a -p run, nothing changes. Hooks and permissions are never on the list.
The plugin's bin/ directory is on the Bash tool's PATH while it is enabled:
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]
tokendoctor-replay [--days <n>] [--window 200k,400k] [--json] # what a smaller window would have saved
The skills are user-invoked only (disable-model-invocation). claude plugin details tokendoctor@tokendoctor estimates about 160 tokens of always-on cost for the four of them. The
plugin has no MCP server. Its hooks module adds the optimize tools (mcp__tokendoctor__*) behind
ToolSearch, so only their names are listed until /tokendoctor:optimize loads them. /tokendoctor
and the slide run in the hooks module too, with no model call, so they add no tokens. Its 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. 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, and info is worth a look. 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 (Pre/PostToolUse, Pos |