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, or -d flags when needed. For skill-level access, see /brewtools:text-optimize.

Quick reference

FieldValue
Modelsonnet
ToolsRead, Write, Edit, Glob, Grep, WebFetch, AskUserQuestion
Skillstext-optimize
Triggers”optimize prompt”, “reduce tokens”, “compress text”, “too verbose”, “deep compress”, “standard compress”
Modeslight, medium, standard (30–50%, human-readable), deep (2–3×, LLM-only with DICT+symbols)

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)

Flow

  1. Determine mode

    Checks your message for a flag (-l, -s, -d) or context hints. No flag: LLM-only files (agents, rules, SKILL.md, KNOWLEDGE.*) → deep; README/docs → standard; unknown → medium.

  2. Load references

    Reads $BT_PLUGIN_ROOT/skills/text-optimize/references/rules-review.md (always). Standard mode also loads standard-compression.md; deep mode loads deep-compression.md. Stops with an error if the base rules file is missing — no optimization without the ruleset.

  3. 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.

  4. Compress

    Light/medium: applies rule groups C → T → S → R → P from rules-review.md. Standard: adds filler removal, paragraph-to-bullet, prose-to-table; targets 30–50% reduction. Deep: builds a DICT header for terms used 3+ times, applies symbol substitutions and structural compression; targets 2–3× reduction.

  5. Verify

    Light/medium: no verification pass. Standard: one round comparing original vs compressed, patches any lost facts. Deep: two rounds — round 1 lists lost or distorted facts and calculates semantic match %; round 2 patches if below 95%, or warns with a loss list if it still falls short.

  6. Report

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

Internals — content type priorities and verification thresholds
Content TypePrimary RulesDefault Mode
System promptC.1-C.8, T.1-T.8, T.10deep
CLAUDE.mdS.1-S.8, T.1-T.8, T.10deep
Agent definitionC.5, C.7, S.2, P.1deep
Skill SKILL.mdS.6, P.1-P.6, R.1-R.3, L.1-L.7deep
DocumentationT.1-T.8, T.10, S.1-S.8, L.1-L.7standard
READMET.1-T.8, T.10, S.1-S.8, L.1-L.7standard
CapabilityWhat the agent does
Token efficiencyCompress without information loss
Logic clarityResolve contradictions and ambiguities
Reference integrityVerify links, paths, cross-references
LLM perceptionStructure for transformer attention patterns

Verification thresholds (deep mode):

  • Round 1: read original + compressed side-by-side, list lost/distorted facts, compute semantic match %
  • Round 2: if match < 95% — patch missing facts and re-verify; if still < 95% — warn user with explicit loss list
  • Light and medium modes skip verification entirely (fast path)
🚀

text-optimize skill

Invoke compression directly as a skill — all four modes, same ruleset.

📄

text-human skill

Reverse direction: remove AI artifacts and humanize machine-written text.

🔗

GitHub source

Agent definition, rule references, and compression spec files.

🧩

Brewtools overview

All brewtools skills and agents — text, secrets, SSH, deploy, debate.

Updating plugins

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