claudeers.
// Claude Plugins

tokendoctor

Claude Code plugin: see where your tokens go, audit your setup against the docs, and tune settings with an approved diff

Actively maintained
99/100
last commit 14 days ago
last release none
releases 0
open issues 0

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up tokendoctor (claude-plugin project) into my current project.
Found on https://claudeers.com/tokendoctor
Repo: https://github.com/rsaryev/tokendoctor
Homepage/docs: https://tokendoctor.dev
Detected install method: claude-plugin → /plugin install tokendoctor@rsaryev/tokendoctor
Category: plugins. Platforms: api, web, mobile.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)
/plugin marketplace add rsaryev/tokendoctor
/plugin install tokendoctor@rsaryev/tokendoctor
// or clone
git clone https://github.com/rsaryev/tokendoctor

// compatibility

Platformsapi, web, mobile
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageJavaScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

tokendoctor

tokendoctor

See where your Claude Code tokens go, and stop wasting them

A Claude Code plugin that measures your real spend, audits your setup against the docs, and changes a setting only after you approve the exact diff. Everything runs on your machine.

Website · Install · Changelog

tokendoctor in a real Claude Code session: /tokendoctor:sessions, then the daily trend

Measure
/tokendoctor:sessions reads your local transcripts: main thread against subagents, spend with a very full context, cache rebuilds. A daily history and before/after snapshots show whether a change helped.
Audit
/tokendoctor:audit runs 33 checks against documented Claude Code behaviour. Each finding links to the docs page it rests on.
Tune
/tokendoctor:optimize proposes changes backed by your own numbers and applies the ones you pick, each through a dialog that shows it.

Install

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.

Use

CommandWhat it does
/tokendoctor:sessions [days]Where tokens went over the last 30 days (or days), with findings. Read-only.
/tokendoctor:auditSetting checks by severity, each linked to the docs. Read-only.
/tokendoctor:optimize [focus]Proposes up to five changes from your numbers and applies the ones you pick.
/tokendoctor:apply <finding-id>Applies one audit fix after a dry run, with a backup of the file.
/tokendoctor:bench save <label> · compareSaves a before/after snapshot of token use, or compares the saved ones, per machine and combined.

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.

From a shell

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> | --since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--project <dir>] [--by day|week] [--json]
tokendoctor-bench save --label <name> [--machine <name>] [--dir <dir>] [--days <n> | --since <date>] [--until <date>]
tokendoctor-bench compare [--dir <dir>] [--json]
tokendoctor-set --list | <key> <value>|--unset [--scope user|project|local] [--write]   # also modelSettings.<model id>.effortLevel
tokendoctor-apply <finding-id> [--scope user|project|local] [--project <dir>] [--write]
What it costs to keep installed

The skills are user-invoked only (disable-model-invocation). claude plugin details tokendoctor@tokendoctor estimates about 205 tokens of always-on cost for the five 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. 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.

The 33 setting checks

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.

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 not run (telemetry or feature-flag fetching off, an advisor alias below the main model's, 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 the main model (Opus when that is Fable), and CLAUDE_CODE_SUBAGENT_MODEL does not move it. Fix installs a Haiku, read-only override.
subagent-model-unsetinfoGeneral-purpose subagents inherit an expensive main model. Fix sets CLAUDE_CODE_SUBAGENT_MODEL=sonnet.
effort-above-defaultinfoA level saved per model by /effort above that model's default (Opus 5.5 at xhigh, say). Fix removes the saved level.
effort-user-key-ignoredinfoA top-level effortLevel in user settings, which Opus 5.5 and later models do not use.
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 (Pre/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.
no-statuslineinfoNo status line. Fix installs tokendoctor-statusline.sh and points statusLine at it (needs jq). One quiet line: Opus 5.5 · api main* · 120k/367k · cache 1h · 5h 51% · week 35% · $24. Tokens are shown against the point where Claude Code compacts; cache 1h is how long the prompt cache stays warm; a limit adds → 100% in 48m only when, at the recent pace (5h: the last hour, week: the last day), it runs out before it resets. The finding also mentions the token-weather mod from anthropics/claude-code-playground as an alternative (needs Claude Code 2.1.287+, shared as-is).

templates/statusline.sh is the status line script the fix installs into your Claude config folder. templates/agents/ holds three generic subagents (Explore, test-runner, docs-lookup), each pinned to a small model with read-only or narrow tools. A plugin cannot override a built-in agent or ship settings.json keys such as autoCompactWindow, env or permissions, so the apply step copies the template into ~/.claude/agents/ or .claude/agents/ and edits your settings files itself, with a backup.

What the session report finds
FindingSeverityWhat it catches
late-compactionwarnOver 30% of main-thread cost spent with more than 400K tokens in context.
subagents-on-top-modelwarnSubagents on Opus or Fable, once one type makes over 5% of all cost; the headline counts every type. Forks always run on the main model.
long-sessionsinfoSessions of 500+ turns, with their share of cost.
idle-cache-rebuildsinfoThe prompt cache rebuilt after it expired during a break.
images-read-repeatedlyinfoThe same image read three or more times.
Limits
  • It reads user, project and local settings files, ~/.claude.json (only the MCP server names, to count them) and your skill and agent folders. It cannot see managed (organisation) settings.
  • Whether a rule helps depends on your plan and workload. Findings explain the trade-off and link to the documentation; decide for yourself.
  • Deny rules in permissions.deny are best-effort for search tools and do not stop a read through Bash.
  • Session costs are in input-token equivalents: each model's API price ratios (cache reads 0.1 of input, 0.05 on Opus 5.5 and Sonnet 5.5, 0.025 on Fable 5.1; Haiku 5.5 prompts over 100K at 5x). Per-model prices are not applied, so the reports speak in shares, not dollars. Sessions on other machines and transcripts Claude Code has already cleaned up are not counted, except for days already in the history file.
Develop
npm test               # node's built-in test runner, no dependencies
npm run test:mod       # the hooks module's tests (claude plugin test)
claude plugin validate .

The landing page lives in site/ (cd site && npm install && npm run dev; npm run build prerenders it, node scripts/og.mjs redraws the social card). The demo is a real session recorded with asciinema; site/scripts/RECORDING.md says how to record it again.

Rules are pure functions over a snapshot (lib/rules.mjs); reading the disk lives in lib/collect.mjs and writing in lib/apply.mjs. Adding a rule means adding one entry and its test. Session analysis is in lib/sessions.mjs and lib/history.mjs, snapshots in lib/bench.mjs, the settings tokendoctor-set may change in lib/tunables.mjs, and the optimize tools in hooks/register.ts.

License

MIT

// faq

What is tokendoctor?

Claude Code plugin: see where your tokens go, audit your setup against the docs, and tune settings with an approved diff. It is open-source on GitHub.

Is tokendoctor free to use?

tokendoctor is open-source under the MIT license, so it is free to use.

What category does tokendoctor belong to?

tokendoctor is listed under plugins in the Claudeers registry of Claude-compatible tools.

13 views
★ 69 stars
unclaimed
updated 25 days ago

// embed badge

tokendoctor on Claudeers
[![Claudeers](https://claudeers.com/api/badge/tokendoctor.svg)](https://claudeers.com/tokendoctor)

// retro hit counter

tokendoctor hit counter
[![Hits](https://claudeers.com/api/counter/tokendoctor.svg)](https://claudeers.com/tokendoctor)

// reviews

// guestbook

0/500

// related in Claude Plugins

🔓

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

// pluginsmultica-ai/★ 230,631[ claude ]
🔓

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…

// pluginsanthropics/⟨Python⟩★ 156,472[ claude ]
🔓

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

// pluginsHKUDS/⟨Python⟩★ 58,467◷ Apache-2.0[ claude ]
🔓

financial-services — a Claude ecosystem project on GitHub.

// pluginsanthropics/⟨Python⟩★ 41,409◷ Apache-2.0[ claude ]
→ see how tokendoctor connects across the ecosystem