text-optimize — deep token optimization
Caution
Verbose prompts waste tokens and blur Claude’s focus. Every filler sentence, passive construction, and prose paragraph that could be a table adds cost and dilutes instruction signal. There is no native “compress this” in Claude Code — you get the full context or nothing.
Tip
30+ validated rules, four modes, parallel processing. The skill reads your files, applies the right rule set for the mode, verifies references, and reports exact before/after metrics. For humanizing AI-generated text, see /brewtools:text-human.
Quick reference
| Field | Value |
|---|---|
| Command | /brewtools:text-optimize |
| Arguments | [-l|-s|-d] [file|folder|path1,path2] |
| Model | sonnet |
| Context | session |
| Tools | Read, Write, Edit, Grep, Glob, Task, AskUserQuestion |
When to use
- Shrink CLAUDE.md — deep mode compresses with a DICT header; LLM-only output, 2-3x reduction
- Clean up agent/skill definitions — medium mode strips filler, converts prose to tables, merges redundant sections
- Prepare user-facing docs — standard mode targets 30-50% compression while staying human-readable
- Light pass on production prompts —
-lremoves filler and fixes tone; structure untouched, safe to apply without review
Modes
| Mode | Flag | Target | Compression | Human-readable |
|---|---|---|---|---|
| Light | -l | Any file | Minimal | Yes |
| Medium | (default) | Any file | Moderate | Yes |
| Standard | -s | Docs, README | 30-50% | Yes |
| Deep | -d | CLAUDE.md, system prompts, agent/skill defs | 2-3x | No — LLM-only |
Auto-detection: when no flag is given, the skill reads the file path and header. CLAUDE.md, .claude/rules/*.md, KNOWLEDGE.* → deep candidate. README.md, docs/ → standard candidate. Ambiguous → asks via AskUserQuestion.
Examples
# Single file, medium mode (default)
/brewtools:text-optimize CLAUDE.md
# Light mode — safe, minimal changes, no restructuring
/brewtools:text-optimize -l .claude/agents/reviewer.md
# Standard mode — 30-50% reduction, stays readable
/brewtools:text-optimize -s README.md
# Deep mode — max compression for CLAUDE.md, review diff after
/brewtools:text-optimize -d CLAUDE.md
# Multiple files in parallel
/brewtools:text-optimize agents/planner.md, agents/executor.md, CLAUDE.md
# All markdown files in a directory
/brewtools:text-optimize -d agents/Natural language also works: "compress this for context" → deep mode. "slim down the README" → standard mode.
Flow
- Parse input
Extracts mode flag, file paths, and any prompt hints (
“deep compress”,“for LLM”). No args → optimizes ALL:CLAUDE.md,.claude/agents/*.md,.claude/skills/**/SKILL.md. - Auto-detect mode
If no flag, classifies each file by path and header. Confident classification runs silently with a short notice. Ambiguous files trigger a single
AskUserQuestionwith mode options. - Analysis phase
Parallel
Exploreagents scan each file for structure, cross-references, and redundancies. Results feed the optimization context. - Optimization phase
Parallel
text-optimizeragents apply the rule set for the selected mode. Deep mode builds a DICT header for repeated terms. Standard mode loadsstandard-compression.mdreference. All modes verify file paths (R.1), URLs (R.2), and circular refs (R.3). - Verification
Standard mode runs 1 verification round comparing compressed vs original — any lost facts get patched. Deep mode runs up to 2 rounds targeting ≥95% semantic match; if still below, warns with a loss list.
- Report
Each file produces a report: lines/tokens before and after, rules applied by ID, issues found and fixed, cross-reference verification status. Files are modified in-place.
Rule categories (30+ rules)
| Category | Rule IDs | Scope |
|---|---|---|
| Claude behavior | C.1-C.8 | Literal following, avoid “think”, positive framing, match style, descriptive instructions, overengineering, avoid ALL-CAPS, prompt format |
| Token efficiency | T.1-T.8, T.10 | Tables, bullets, one-liners, inline code, abbreviations, filler, comma lists, arrows, strip whitespace |
| Structure | S.1-S.8 | XML tags, imperative, single source, context/motivation, blockquotes, progressive disclosure, consistent terminology, ref depth |
| Reference integrity | R.1-R.3 | Verify file paths, check URLs, linearize circular refs |
| Perception | P.1-P.6 | Examples near rules, hierarchy, bold keywords, standard symbols, instruction order, default over options |
| LLM Comprehension | L.1-L.7 | Critical info position, documents-first, conciseness, quote-first, add WHY, reiterate constraint, prompt repetition |
Mode-to-rules mapping:
| Mode | Applies | Notes |
|---|---|---|
| Light | C.1-C.8, T.6, R.1-R.3, P.1-P.4, L.1-L.7 | Text cleanup only — no restructuring |
| Medium | All rules (C + T + S + R + P + L) | Balanced transformations |
| Standard | All rules + standard-compression.md | 30-50% compression, 1 verification round |
| Deep | All rules + deep-compression.md | DICT header, symbol substitutions, 1-2 verification rounds |
Text Human
Remove AI artifacts and humanize content — the complement to text-optimize.
text-optimizer agent
The subagent that handles single-file optimization in parallel batches.
GitHub source
Source code, rule references, and compression guides.
Brewtools overview
All brewtools skills — text, SSH, deploy, debate, plugin management.
Updating plugins
/brewtools:plugin-update to check and update the brewcode plugin suite in one command.
See the FAQ for details.