# Token Doctor

> >

- **Type:** Skill
- **Install:** `agentstack add skill-enmr10-token-doctor-token-doctor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [enmr10](https://agentstack.voostack.com/s/enmr10)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [enmr10](https://github.com/enmr10)
- **Source:** https://github.com/enmr10/token-doctor/tree/main/skills/token-doctor

## Install

```sh
agentstack add skill-enmr10-token-doctor-token-doctor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Token-Doctor

Measure and cut the token cost of the files that load into every prompt.

## When to run

- A `CLAUDE.md` / `AGENTS.md` / memory file has grown large
- Prompts feel expensive or context fills up fast
- Before committing context files (keep them lean)
- As a CI gate so no context file silently bloats

## Input

A single file, or a directory (scans `*.md`, `*.txt`, `CLAUDE.md`, `AGENTS.md`,
`llms.txt`, etc.; skips code, `node_modules`, `.git`).

## How to run

The engine lives in `scripts/` (Python 3.8+ stdlib, zero dependencies).

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

# Audit a single file
python3 -m scripts CLAUDE.md

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

# CI gate: fail if any context file exceeds a token budget
python3 -m scripts /path/to/project --fail-over 1500

# Machine-readable
python3 -m scripts /path/to/project --format json --out audit.json
```

## What it does

1. **Measures** estimated tokens per file (offline heuristic; % saved is reliable).
2. **Splits** each file into prose vs protected regions (code, inline code, URLs,
   paths, tables, frontmatter).
3. **Reduces** ONLY prose: drops filler, shortens verbose phrases, collapses blank
   bloat, removes duplicate adjacent lines.
4. **Reports** before/after tokens, % saved, biggest-savings files, and waste findings.
5. **Applies** safely on `--apply` (writes `.bak` first).

## Guarantees

- **Never edits** fenced code, inline `code`, URLs, markdown links, file paths,
  env vars, tables, or YAML frontmatter — these survive byte-for-byte.
- **Read-only by default.** `--apply` always writes a `.bak` backup.
- Meaning is preserved; only token-wasteful wording is trimmed.

## Waste codes

| Code | Severity | Meaning |
|------|----------|---------|
| `LARGE_FILE` | 🔴 | File exceeds the token budget (taxes every prompt) |
| `FILLER_HEAVY` | 🟡 | Many removable filler words |
| `VERBOSE_PHRASES` | 🟡 | Wordy phrases that have short equivalents |
| `DUPLICATE_LINES` | 🟡 | Repeated adjacent lines |
| `HUGE_CODE_BLOCK` | 🔵 | A code/log block dominates the file |
| `BLANK_BLOAT` | 🔵 | Runs of blank lines |

## Workflow for the agent

1. **Run** the audit on the user's project or file → read the report.
2. **Summarize** total % savings and the biggest-savings files.
3. **Offer** `--apply` (explain the `.bak` backups) before changing anything.
4. **For LARGE_FILE / HUGE_CODE_BLOCK**, suggest moving detail into `references/`
   loaded on demand rather than the always-loaded file.
5. **Re-run** to confirm the new token total.

See `references/methodology.md` for the estimator and `references/preservation.md`
for exactly what is never touched.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [enmr10](https://github.com/enmr10)
- **Source:** [enmr10/token-doctor](https://github.com/enmr10/token-doctor)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-enmr10-token-doctor-token-doctor
- Seller: https://agentstack.voostack.com/s/enmr10
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.