`commitbrief compress`: an LLM rewriting another LLM's system prompt — and the discipline that keeps it safe.

A COMMITBRIEF.md that has grown for six months tends to bloat. Sentences that started as crisp rules drift into hedged paragraphs. Examples that were helpful at month one become noise at month six. Rules added “just in case” never get pruned. The file works, but it costs more tokens than it should, and the model’s signal-to-noise on each call quietly degrades.

commitbrief compress is the answer to that drift. It is also a contested design choice: a model rewriting another model’s system prompt. This post explains how compress works, why it ships with three conservatism levels, and what guardrails keep it from ever destroying your rules file.

What the command does

commitbrief compress --level balanced

That single command runs the following pipeline:

1. Read the current COMMITBRIEF.md from the repo root.
2. Wrap it in <user_rules>...</user_rules> (the same injection-defense pattern used everywhere else).
3. Send it to your configured provider with the compression system prompt for the chosen level.
4. Strip preamble and code-fence wrappers from the returned text.
5. Compare character and token counts before and after; refuse to apply if the result isn’t smaller.
6. Print a summary: chars/tokens before, after, savings per estimated review run, and the cost of the compression call itself.
7. Ask [y/N] (or accept --yes).
8. Back up the original to .commitbrief/backups/COMMITBRIEF-<ISO-timestamp>.md.
9. Atomically write the new content via temp file plus rename.

Each of those steps exists because a previous version of compress made the wrong call in production and someone lost work. The current shape is what survived.

Why three levels

The compression prompt is the lever. Three of them ship embedded in the binary:

• light — only collapses redundant phrasing and trims explicit duplicates. Won’t restructure sections or rewrite examples. Output is recognizable as your original, with about 10–25% fewer tokens.
• balanced (default) — restructures where it makes the file shorter without changing meaning, normalizes formatting, collapses similar bullets. Typically 30–50% fewer tokens.
• aggressive — rewrites rules into the tersest defensible form, including substituting domain shorthand for full phrases. Will sometimes turn a paragraph into a single bullet. Can hit 50–70% reduction.

light is for the cautious — when your rules file embeds carefully worded constraints you don’t want a model to paraphrase. aggressive is for the file you’re going to read again right after compression and verify line by line. balanced is what you’ll use 90% of the time.

Why three rather than a single dial? Because the conservatism choice is qualitative, not numeric. “How much do I trust the model to preserve nuance?” doesn’t map cleanly to a percentage. Three named profiles force you to make a categorical decision and accept the trade-off that goes with it.

The “refuse when not smaller” rule

If the compressed output has more characters than the original, compress refuses to write it. The summary prints, the prompt asks nothing, the file is untouched. This rule sounds obvious until you remember what it actually prevents: a model that, on a bad day, decided your rules file would benefit from being “more thorough” and added three paragraphs of clarification you never asked for.

This guard is the single most important piece of the design. Without it, a routine monthly run could silently double your file under the disguise of “compression.” With it, the worst case is that you spent one provider call’s worth of tokens to learn the model couldn’t improve on what you have.

Automatic backup, atomic apply

Even when the output is smaller and you confirm the prompt, the original isn’t overwritten in place. Two layers of safety:

• Backup: the original is copied to .commitbrief/backups/COMMITBRIEF-<ISO-timestamp>.md before anything else happens. The timestamp uses Windows-safe formatting (no colons) so the same backup path works across platforms.
• Atomic apply: the new content is written to a temp file, then renamed over the original. If the process is interrupted between the write and the rename, the original is still intact.

You can undo any compression with one cp from the backup directory. The directory is gitignored by default — these are local working files, not history.

Writing somewhere else with --out

Sometimes you want to see the compressed version without touching the original. --out <path> does that:

commitbrief compress --level aggressive --out COMMITBRIEF.compressed.md

The compressed text lands at the path you gave; the original isn’t read for backup, isn’t overwritten, isn’t touched at all. Useful when you want to A/B test a compressed rules file against the original in CI, or when you’re not ready to commit to the new shape.

Practical economics

If you run CommitBrief 50 times a week on a 2,800-token COMMITBRIEF.md, a balanced compression to 1,400 tokens cuts your weekly input by 70,000 tokens. At typical commercial-tier pricing that’s small change individually but adds up across a team. The provider-side prompt cache absorbs most of the rest, which is why I recommend running compress no more than once a month — repeated re-compressions of an already-compressed file produce diminishing returns and risk meaning drift.

Run it after a meaningful change to the rules file, not on a cron. Compress is a maintenance tool, not a background job.

What compress does not do

Compress only touches COMMITBRIEF.md. It does not touch OUTPUT.md, your .commitbriefignore, or any other configuration file. It does not “improve” your rules — it only shortens them. If a rule is poorly worded, compress will preserve the poorness in fewer tokens.

For real improvements to the rules themselves, the COMMITBRIEF.md anatomy post is the right starting point. Compress is what you reach for once your rules are already good and you just want them denser.

The next post turns to a different audience — the solo developer, the indie hacker, the open-source maintainer who doesn’t have anyone to review their PRs in the first place.

---

← all posts