Compress command

Home / Commands / compress

commitbrief compress

Shrink the repo's COMMITBRIEF.md via the configured LLM provider. A long, mature rules file racks up input tokens on every review; compression keeps the same semantics with fewer characters.

Synopsis

commitbrief compress [--level=balanced] [--out=<path>] [--dry-run]

Requires a COMMITBRIEF.md to exist at the repo root. If it does not, compress errors with a pointer to commitbrief init.

Levels

Level	Target reduction	Notes
light	~20–30%	Preserves examples. Safe first attempt.
balanced	~40–60%	Default. The pragmatic middle.
aggressive	~60–80%	May merge similar rules. Re-read the result before accepting.

Each level uses a distinct embedded system prompt — same provider, different compression policy.

Behavior

1. Read the current COMMITBRIEF.md.
2. Resolve the active provider + model (CLI override flags apply: --provider, --model).
3. Call the provider with a compression-specific system prompt and the file contents as the user message.
4. Compare sizes. If the result is larger than the original (rare; usually means the model failed to compress), abort with compress: aborted: <reason> (no files changed).
5. Print the result block (sizes, savings, per-review saved $, compression call cost, latency).
6. Branch on flags:
   • --dry-run: print "Dry run — COMMITBRIEF.md was NOT modified. Re-run without --dry-run to apply." and exit. No file changes.
   • --out=<path>: write the compressed text to <path> and leave COMMITBRIEF.md untouched.
   • Default: prompt for confirmation (TTY) or abort (non-TTY) unless --yes is set. On accept, back up the original to .commitbrief/backups/COMMITBRIEF.md.<UTC-ISO-timestamp>.bak and replace COMMITBRIEF.md.

Warning

The compression call always fires under --dry-run — you pay the tokens, you just do not pay the write. That is the point: see what the model would produce before committing.

Flags

Flag	Notes
--level=<light|balanced|aggressive>	Default balanced. Invalid values error before any provider call.
--out=<path>	Write the compressed text to a file instead of replacing COMMITBRIEF.md.
--dry-run	Preview the result block; do not write or back up. Mutually exclusive with --out.

The global --yes flag bypasses the "replace COMMITBRIEF.md?" confirmation when --out and --dry-run are not in play.

Output

The Compressing … line is a staged-tree progress stage (the same display the review command uses): it animates on a TTY, prints one line per transition in non-TTY/CI logs, and is suppressed by --quiet. The result block below it goes to stdout.

⏺ Compressing /repo/COMMITBRIEF.md with provider=anthropic model=claude-opus-4-7 level=balanced …
Original:   8421 chars / ~2105 tokens
Compressed: 4123 chars / ~1030 tokens
Reduction:  51.0% (1075 tokens)
Per-review input savings: $0.00161 (at claude-opus-4-7 rate)
Compression call cost: in=2127 out=1041 (≈$0.04719), latency 14.231s
Backed up original to /repo/.commitbrief/backups/COMMITBRIEF.md.20260527T182913Z.bak
Wrote compressed /repo/COMMITBRIEF.md

Examples

# Preview a balanced compression without writing.
commitbrief compress --dry-run

# Apply the default (balanced) compression with confirmation.
commitbrief compress

# Aggressive compression to a sidecar file for review.
commitbrief compress --level=aggressive --out=COMMITBRIEF.compressed.md

# Apply without confirmation (CI / scripts).
commitbrief compress --yes

Recovery

Backups live under .commitbrief/backups/. To restore the previous COMMITBRIEF.md:

cp .commitbrief/backups/COMMITBRIEF.md.20260527T182913Z.bak COMMITBRIEF.md

See also

• COMMITBRIEF.md — the rules file this command shrinks.
• Init command — create the rules file compress requires.
• Cost preflight — how the compression call's cost is gated.
• Providers — the provider that performs the compression.