Gobstopper
CLI
Detect, plan, apply, verify, undo — every step inspectable before anything changes.
gobstopper plan <session> --trigger 250000
gobstopper apply <session> --strategy elide
gobstopper verify <session> && gobstopper undo <session>Compact, resume, and audit every agent session.
gobstopper is the first cross-provider context compactor that preserves a content-addressed archive of every conversation state, resumes compacted sessions on both Claude Code and Codex, and proves the savings on real API calls.
Free and MIT licensed. Rust 1.85 or newer, local transcripts, no account. First Gobstopper release in preparation — install from source today.
$ claude --resume 034... --autocompact 100
# provider added 59 records, removed 0
$ gobstopper apply 034... --in-place --strategy compacted
# elided 43 records, injected digest, resumed cleanly
$ gobstopper diff 034-original 034-compacted
removed: 43 added: 46 (43 stubs + 3 tail records)A policy over your transcripts, not a new editor.
Providers compact late — near the top of the context window, where every turn is most expensive and recall is already degrading. Gobstopper moves the boundary down and lets you choose what happens there.
Session detection
Scans Codex and Claude Code transcript stores for live and idle sessions, reading each provider's own token-usage records — real context size where available, with a fallback estimate otherwise.
A small edit IR
Every strategy lowers to the same edits — elide, inject digest, provider compact — and the host validates the candidate before publication. Provider linkage (parent chains, ordinals) is never removed, only rewritten in place within a line.
Strategies
auto picks by transcript shape; sawtooth delegates to the provider's native compaction; elide masks stale tool output; structured emits a conservative state-card placeholder; agentic is reserved for a bounded editor-model backend.
Presets, plugins and config
Global defaults, per-provider and per-session overrides, named presets, an explicitly-trusted legacy command hook, and versioned plugin bundles with exact artifact identity and host-side edit validation.
Undo vault
Every apply snapshots the transcript into a content-addressed vault first. gobstopper undo restores byte-identical bytes into a new fork — the original transcript is never overwritten by a standalone compaction.
Telemetry and eval
Every mutation emits a compaction event for dashboards. gobstopper eval runs all strategies on temp copies and scores structural retention; it is a regression signal, not a live cost measurement.
One policy, three ways in.
The same plans, edits, and safety rails underneath each entry point. There is no agent-only path behind the convenient one.
Watcher and hooks
A polling daemon that stages a plan before the threshold and publishes a validated copy when crossed — or provider hooks that snapshot and log around native compaction.
gobstopper watch --trigger 250000 --double-buffer
gobstopper install-hooks # Claude settings + Codex hooks.jsonYour program
preset.command receives normalized transcript JSON and returns edits. A versioned plugin bundle declares capabilities and a checked executable for the same seam.
[presets.my-policy]
strategy = "elide"
keep_recent_tool_outputs = 4
[presets.custom]
command = ["node", "my-editor.js"]What Gobstopper will not do.
Compaction that breaks a resume chain or hides a failure is worse than none. The constraints are enforced in code, not promised in prose.
Small enough to trust.
These rules are enforced by the command surface and its tests, not by convention.
- Transcripts are never destroyed
- Rewrites replace payload content inside existing lines, never deleting records, so provider resume chains stay valid. Standalone compaction publishes a separate, verified transcript copy; the source file is left unchanged. A verified snapshot exists before any byte changes, and gobstopper verify checks structural integrity after.
- Provider keeps live authority
- On a running session Gobstopper asks the provider's own compaction machinery instead of editing files under it. Custom transcript surgery stays an offline operation on idle sessions and forks.
- Honest outcomes
- A provider-side compaction that fails is recorded as failed — quota rejections included. Eval reports structural retention and verify findings, not measured subscription savings. Public claims distinguish occupancy models from completed benchmarks.
Install and compact your first session.
First Gobstopper release in preparation — install from source
cargo install --git https://github.com/hraness/gobstopper gobstopper
gobstopper --helpgobstopper detect
gobstopper plan <session> --trigger 250000
gobstopper watchNeeds Rust 1.85 or newer. Reads Codex and Claude Code transcripts locally; nothing leaves the machine. Read the full reference.
Before you install.
How much does it actually save?
Compaction lowers context occupancy in a sawtooth model: average context per turn is roughly (trigger+floor)/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 runs. We report file-byte changes and observed provider usage where available; we do not claim dollar or quota savings without a completed benchmark.
Does it edit my live session?
Standalone `apply` or `watch` produces a separate, validated transcript copy and leaves the source unchanged. For a session the provider is actively serving, Gobstopper delegates to provider-native compaction — Codex thread/compact/start over the app-server protocol, Claude /compact through stream-json. Local rewrites only touch idle transcripts, and always with a vault snapshot first.
What if a compaction loses something important?
gobstopper undo restores the exact bytes into a new fork, leaving the current transcript untouched. gobstopper eval replays every strategy against a transcript copy and reports probe recall — which verbatim details survived — plus post-rewrite integrity findings, so you can pick a strategy with evidence before trusting it live.
Which agents does it support?
Codex and Claude Code today, over their real transcript formats. The edit IR is provider-neutral, so another JSONL-transcript agent needs only a small adapter.
Can I run my own compaction logic?
Yes — a `preset.command` pipes normalized transcript JSON to a program and applies the edits it returns, or a versioned `gobstopper-plugin.json` bundle declares capabilities and a checked executable. Host-side validation bounds every proposal: no edit can grow the transcript, skip protected recent output, bypass linkage checks, or exceed digest size. Trusted subprocesses are not security sandboxes, so explicit trust and artifact identity are required.
Who made it?
Ben Guo, a musician and builder, formerly a founder and engineering leader at companies including Venmo and Stripe, now building from Puerto Rico. Gobstopper is published by Hraness under the MIT license.
Built by Ben Guo
Gobstopper is built by Ben Guo, a musician and builder, formerly a founder and engineering leader at companies including Venmo and Stripe, now building from Puerto Rico. It is published by Hraness under the MIT license.
Let long sessions stay long — and cheap.
Set a trigger, pick a strategy, and stop paying for the same 900k tokens on every turn.
Free and MIT licensed. Rust 1.85 or newer, local transcripts, no account. First Gobstopper release in preparation — install from source today.