rsaryev/tokendoctor

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

Summary

tokendoctor is a TypeScript Claude Code plugin for seeing where tokens go, auditing a setup against Claude Code documentation, and tuning settings through reviewed diffs. It combines session analysis, configuration checks, a local dashboard, and reversible changes; investigation commands are read-only, and optimization writes only after explicit approval.

What it is useful for

Engineers can use it when token use is hard to explain or their Claude Code configuration may contain stale or ignored settings.

• /tokendoctor:sessions [days] estimates what smaller context windows would have saved by replaying recorded sessions, then shows where tokens went. It also identifies issues such as late compaction, expensive subagents, long sessions, and repeated image reads.
• /tokendoctor:audit runs 31 checks against the documentation and your settings, memory, CLAUDE.md, skills, and agents. Findings cover problems such as invalid settings JSON, the unsupported autoCompactThreshold key, disabled auto-compaction, costly default models, long instructions, and large directories that are not denied.
• /tokendoctor:optimize [focus] proposes up to five changes based on measured usage. Each change is displayed first and runs only when Apply is selected. Hooks and permissions are not on the optimization list.
• /tokendoctor:dashboard [days] creates one local HTML file with spend by day, token type, model, effort, project, context size, main thread, and subagent type. The dashboard opens locally without a network connection.
• /tokendoctor slide on replaces old tool output with short pointers when Claude Code would summarize, keeping prompts, answers, and decisions word for word. This can avoid a summary pause, although one documented Sonnet run missed one of eight remembered details.
• /tokendoctor undo [n] lists changes and restores a selected one without a model call.

How engineers can use it

Install the plugin with the documented commands:

claude plugin marketplace add rsaryev/tokendoctor
claude plugin install tokendoctor@tokendoctor

To try it without installing, clone the repository and run:

claude --plugin-dir /path/to/tokendoctor

Start with /tokendoctor:sessions 30 to establish a baseline, followed by /tokendoctor:audit. Use /tokendoctor:optimize only after reviewing the proposed diffs, then inspect /tokendoctor:dashboard and undo individual changes if needed. While the plugin is enabled, its CLI tools are also available from the Bash tool’s PATH, including tokendoctor-audit --json and tokendoctor-sessions --days 30 --json.

Important limits include inability to see managed organization settings, missing sessions from other machines or already-cleaned transcripts, and cost estimates based on API list prices rather than plan-specific weighting. Permission deny rules also do not prevent reads through Bash.