token-doctor 🪙 — Measure & Reduce Claude Token Usage

token-doctor is an open-source Claude Code skill that audits your context files (CLAUDE.md, AGENTS.md, memory files, docs), measures how many tokens they cost, finds the waste, and safely compresses the prose — while never touching code, links, file paths, or tables. It tells you exactly how many tokens you'll save before you change a thing.

Every prompt re-loads your CLAUDE.md and memory files. If they're bloated, you pay for that bloat on every single turn. token-doctor finds the waste and trims it losslessly — same meaning, fewer tokens.

The problem: your context files are taxed on every prompt

CLAUDE.md, AGENTS.md, and memory files load into context at the start of every request. Verbose wording, filler words, repeated lines, and oversized blocks cost tokens repeatedly — across thousands of turns. Most teams never measure it, so it silently grows.

What token-doctor does

Quick start

# Audit (read-only) — see token cost + achievable savings
python3 -m scripts /path/to/project

# Audit one file
python3 -m scripts CLAUDE.md

# Apply the reductions (keeps CLAUDE.md.bak)
python3 -m scripts CLAUDE.md --apply

# CI gate
python3 -m scripts /path/to/project --fail-over 1500

No install, no pip, no API key, no network.

Real results

token-doctor is honest — it only reports savings that exist:

It found 10 filler words and 30 verbose phrases in the bloated file, and did not invent savings on the clean one. That calibration is the point: it trims waste, not good writing.

What it preserves (byte-for-byte)

Code blocks · inline code · URLs · markdown links · file paths · $ENV_VARS · tables · YAML frontmatter. Only prose is ever rewritten. See preservation.md.

How token counting works

Exact counts need a model tokenizer; to stay offline and zero-dependency, token-doctor blends a char-based and word-based estimate:

estimate = (chars/4 + words*1.33) / 2  + punctuation-density bump

The absolute number is an estimate, but the percentage saved is reliable because before/after use the same estimator. Full rationale in methodology.md.

Installation

Claude Code plugin marketplace

/plugin marketplace add enmr10/token-doctor
/plugin install token-doctor

Manual

Upload token-doctor.zip via Add Skill, or copy skills/token-doctor/ into your skills directory.

Requirements

• Python 3.8+ (standard library only — zero dependencies)
• Runs offline; no API key, no network, no telemetry
• Cross-platform; UTF-8 safe even on Windows consoles

FAQ

How do I reduce my Claude token usage?

Run python3 -m scripts /path/to/project. token-doctor reports how many tokens your context files cost and how many you'd save, then --apply trims them safely.

Will it break my CLAUDE.md or code snippets?

No. It never edits code blocks, inline code, URLs, file paths, links, or tables — only prose. --apply always keeps a .bak backup.

Is the token count exact?

It's a calibrated estimate (offline). The percentage saved is reliable because before and after use the same estimator. Pipe the result through your model's tokenizer if you need exact numbers.

Can I use it in CI?

Yes — --fail-over N exits non-zero if any context file exceeds N tokens, so bloat fails the build.

How is this different from a summarizer?

A summarizer rewrites and can lose detail. token-doctor only removes provably wasteful wording (filler, verbose phrases, duplicates) and protects everything technical.

Keywords

Claude token usage · reduce tokens · CLAUDE.md optimization · context window · token cost · compress context · trim memory file · prompt cost · token budget · Claude Code skill · context engineering · agent context optimization

Related

• skill-doctor — audits a skill library for description collisions (the wrong-skill-triggers problem).

License

MIT — see LICENSE.

Built with Claude. Last updated: 2026-06-16.