Verbose docs cost tokens. The optimizer earns them back.

Caution

Every redundant word in a CLAUDE.md, agent definition, or system prompt is a token Claude reads on every turn. At scale — multi-agent sessions, long-running tasks, compact-heavy workflows — that overhead compounds. Standard prose writing habits produce 2–3x more tokens than necessary for LLM consumption.

Tip

Mention the target file and intent — the agent picks the right mode automatically. LLM-only files (agents, rules, SKILL.md) default to deep; user-facing docs default to standard. Override with -l, -s, -d, or -x (opt-in) flags when needed. For skill-level access, see /brewtools:text-optimize.

Quick reference

Field	Value
Model	sonnet
Tools	Read, Write, Edit, Glob, Grep, Bash, WebFetch
Skills	text-optimize
Triggers	”optimize prompt”, “reduce tokens”, “compress”
Modes	`light`, `medium` (default), `standard` (30–50%, human-readable), `deep` (2–3×, LLM-only with DICT+symbols), `max` (opt-in, 3–4×, `-x`/`--max`)
Scope	One bounded unit per run — one deliverable, ~5 files, ~10 steps

Scope guard

The agent sizes the job before it starts compressing.

Situation	What the agent does
Task fits one bounded unit — one deliverable, ~5 files, ~10 steps	Runs it
Bigger, or several independent deliverables	Stops before starting, returns a split proposal: 2-N bounded subtasks, each with scope and suggested owner
Scope grows mid-flight	Stops at the next clean boundary, reports done / remaining / how to split
Brief missing GOAL, SCOPE, CONTEXT, CONSUMER or acceptance	States the assumption in the report. It cannot ask — a subagent has no question channel — so an open decision comes back to the caller as a named option plus a recommendation, never a guess. Never invents scope

“Optimize every file in .claude/” comes back as a split proposal, not as an hour of unsupervised rewriting. Point it at one file or one tight group and it runs straight through.

When to use

Bloated CLAUDE.md — project instructions grown beyond control; deep mode trims to the minimum Claude needs
Agent/skill definitions — trim prose, tighten trigger lists, remove filler from system prompts
README or docs/ — standard mode cuts verbosity while keeping the file human-readable
Pre-release token audit — run before bumping a version to catch regressions in instruction size
Rules files — .claude/rules/*.md often accumulate redundant explanations; deep removes them safely

Examples

"Optimize this prompt for fewer tokens"
"This CLAUDE.md is too long, compress it"
"Make this more token-efficient"
"deep compress brewtools/agents/text-optimizer.md"

# Explicit mode flags (passed as part of your message)
"optimize -d brewcode/.claude/agents/developer.md"   # deep
"optimize -s web/docs/README.md"                      # standard
"optimize -l my-notes.md"                             # light (structure only)
"optimize -x brewcode/.claude/agents/developer.md"    # max (opt-in)

Flow

Determine mode
Checks your message for a flag (-l, -s, -d, -x) or context hints. No flag: LLM-only files (agents, rules, SKILL.md, KNOWLEDGE.*) → deep; README/docs → standard; unknown → medium (default). -x/—max is opt-in only — never auto-selected.
Load references
Reads ${CLAUDE_PLUGIN_ROOT}/skills/text-optimize/references/rules-review.md (always). Standard mode also loads standard-compression.md; deep mode loads deep-compression.md; max mode loads both deep-compression.md and max-compression.md. Stops with an error if the base rules file is missing — no optimization without the ruleset.
Analyze target
Reads the file, identifies content type from the priority table (system prompt / CLAUDE.md / agent / skill / doc / README), measures baseline lines and token estimate, notes critical facts to preserve.
Dedup pass
Before compressing (all modes): builds a numbered atomic-fact inventory and flags repeats (exact, reworded, cross-format).
- Merge accidental dups into the most specific statement (D.1–D.3)
- Cap intentional emphasis at 2 per document — full form early, short echo at the end (D.4)
- Different scope, numbers, or conditions = different facts, never merged (D.6)
- Multi-file runs: D.5 is decided by the orchestrator, not this agent — it applies only the dedup rows named in its brief, each row a canonical location plus a pointer carrying a 1-line summary, never a bare pointer that loses the fact it replaces. Deep/max log a dedup ledger

Compress

Applies the ruleset for the chosen mode, escalating technique and target ratio:

Mode	Adds	Target
Light/medium	Rule groups C → T → S → R → P (rules-review.md)	—
Standard	+ filler removal, paragraph-to-bullet, prose-to-table	30–50%
Deep	+ DICT header (terms used 3+×), symbol substitutions, structural compression, aggressive lossy pass (A.1 fusion → A.3 paraphrase → A.2 word drop → A.4 known-fact elision)	2–3×
Max (opt-in)	+ atomic fact-lines, ASCII operator dialect, format-aware tables, Chain-of-Density pass, same aggressive lossy pass as deep	3–4×

Deep/max log every A.2 drop and A.4 elision to a loss ledger alongside the dedup ledger — A.1 fusions and A.3 paraphrases are not losses, they’re recorded as merged/kept.

Verify

Verification scales with mode. Dedup-merged facts always count as preserved, never as loss. A.1 fused and A.3 paraphrased facts also count as preserved; A.4 elisions get a distinct elided-known label and are checked against the same gate as any other loss. A.2 drops are ledgered but gate-neutral; a drop that degrades meaning marks the fact distorted.

Mode	Rounds	Gate
Light	none	—
Medium	self-check vs fact inventory	zero loss
Standard	1	(kept + merged) / total ≥ 98%
Deep	1-2	round 2 patches if match < 95%
Max	2 (mandatory, independent self-QA probe)	≥ 95% overall + 100% on numbers/names/negations/scope

Report
Outputs ## Optimization Report: [filename] with a metrics table (lines / chars / words / ~tokens — before, after, change%, ratio), semantic match % for standard/deep/max, rule IDs applied, issues fixed, verification result, and a dedup summary (N merged, N emphasis repeats capped).

Internals — content type priorities and verification thresholds

Content Type	Primary Rules	Default Mode
System prompt	C.1-C.8, T.1-T.8, T.10	deep
CLAUDE.md	S.1-S.8, T.1-T.8, T.10, D.1-D.6	deep
Agent definition	C.5, C.7, S.2, P.1	deep
Skill SKILL.md	S.6, P.1-P.6, R.1-R.3, L.1-L.8	deep
Documentation	T.1-T.8, T.10, S.1-S.8, D.1-D.6, L.1-L.8	standard
README	T.1-T.8, T.10, S.1-S.8, L.1-L.8	standard

A.1-A.4 (aggressive lossy) apply whenever the resolved mode is deep or max, regardless of content type.

Verification thresholds:

Light: no verification pass
Medium: self-check — re-check fact inventory against output, zero loss required
Standard: 1 round — fact inventory original vs compressed, gate (kept + merged) / total ≥ 98%, patch any slips
Deep — Round 1: atomic-fact inventory from the original, each fact labeled kept/merged/lost/distorted, match % = (kept + merged)/total
Deep — Round 2: if match < 95% — patch missing facts and re-verify; if still < 95% — warn user with explicit loss list
Max — Round 1: claim inventory (one predicate per claim), labels kept/merged/lost/distorted/elided-known, match % = (kept + merged)/total
Max — Round 2 (mandatory, independent): self-QA probe of 10–20 questions from the original, answered from the compressed text only. Gates: ≥ 95% overall + 100% sub-gate on numbers, names, negations, and scope qualifiers

Return Contract

Verdict first, <=30 lines, path:line — never the optimized text, before/after excerpts, or the full ledgers pasted back into the reply. One line per file: sizes before → after, change %, semantic match %, rule IDs applied, verify pass/fail, dedup count. Ledgers and fact inventories go straight to .claude/reports/YYYYMMDD-HHMMSS_text-optimize/report.md; the reply returns that path plus the headline numbers.

/brewtools:agent-return-setup enforces this at ~1000 / ~2500 est-tokens when installed; the contract itself ships unconditionally.

🚀

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.

Verbose docs cost tokens. The optimizer earns them back.

Caution

Tip

Quick reference

Scope guard

When to use

Examples

Flow

Return Contract

text-optimize skill

text-human skill

GitHub source

Brewtools overview

Updating plugins