Method

Methodology

Gobstopper compares how compaction changes context size and which details survive; you choose a threshold and strategy, then inspect the result. Saved-session edits produce separate copies so you can compare the result with the original.

Occupancy model

Context is a sawtooth. If you compact at trigger T and the summary floor is F, steady-state context occupancy per turn is roughly (T+F)/2. A 250k/40k policy is ~3.3x lower occupancy than a 1M-window default, and 150k/20k is ~5.6x lower.

These are occupancy projections, not measured subscription savings. Real cost depends on cache hit rates, billing for summary turns, re-fetches from lost detail, and how often compaction itself runs.

Strategies

auto, the default, recommends the provider's own controls for a live session and compares eligible file strategies for an idle one.
sawtooth proposes provider compaction. Automatic provider compaction is disabled.
elide replaces eligible stale tool output with short stubs, oldest first, until the estimated context reaches the floor or no eligible output remains.
cliff keeps the head, the newest three assistant steps, and the newest eight tool results byte-for-byte and drops older eligible tool results over 500 bytes. It has no floor and adds no state card; the comparison with CliffCompaction explains where the rule comes from. For running sessions in Claude Code, Codex, and OpenAI-compatible agents, gobstopper proxy applies CliffCompaction's summary rule to each outgoing request instead of a copy, keeping the latest three turns by default.
compacted does the same and adds a state card summarizing the hidden work. Codex-native compacted records are experimental and need --experimental-compacted.
structured writes a conservative state card from transcript metadata. It does not summarize meaning.
agentic accepts edits proposed by a command or plugin you trust, and Gobstopper still validates each one.

The documentation lists every strategy, includingcache_aware, scored, dedupe,micro, and middle.

Structural diff and the undo vault

Before writing a separate copy, Gobstopper stores the original and prepared bytes in a local vault indexed by content hashes. Snapshots are split into deduplicated 1 MiB chunks, so a transcript that only grew reuses the storage of its unchanged beginning.

gobstopper diff compares two snapshots by record hash and reports which records were added, removed, and kept. A new copy has a new session identity, so its metadata changes appear alongside the compaction edits.

What the numbers mean

File-byte changes show what a saved copy removed; provider usage shows what a live request consumed. Billing also depends on cache prices and the provider's plan. gobstopper bench runs the built-in strategies over your discovered sessions and writes a CSV of projected savings, verify errors, and probe recall. The published studies report their cohorts, no-ops, and limitations separately.