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 earlier. Spend less. Keep the thread.
Automatic context compaction for coding-agent sessions — Codex and Claude Code today, any JSONL-transcript agent tomorrow.
Free and MIT licensed. Rust 1.85 or newer, local transcripts, no account. First Gobstopper release in preparation — install from source today.
$ gobstopper detect
claude_code 4f3a… active context ~231k tokens lifetime ~416M in
$ gobstopper plan 4f3a --strategy auto
context: 93k -> ~40k tokens (saves ~53k)
strategy: elide — 10 stale tool outputs masked, tail preserved
$ gobstopper watch --trigger 250000A 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, not an estimate.
A small edit IR
Every strategy lowers to the same edits — elide, inject digest, provider compact — applied in place so parent chains and ordinals never break.
Strategies
auto picks by transcript shape; sawtooth delegates to the provider's native compaction; elide masks stale tool output; structured writes a state-card digest; agentic hands bounded keep/elide/summarize tools to a small editor model.
Presets and config
Global defaults, per-provider and per-session overrides, named presets, and a preset.command escape hatch that runs your own edit program over normalized transcript JSON.
Undo vault
Every apply snapshots the transcript into a content-addressed vault first. gobstopper undo restores byte-identical — and the undo itself is snapshotted.
Telemetry and eval
Every mutation emits a compaction event for dashboards. gobstopper eval runs all strategies on temp copies and scores what the compacted session still recalls.
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 swaps it in 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. The agentic preset runs a bounded editor model over 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 are in-place stubs, not deletions — provider resume chains stay valid. 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 probe recall and verify findings, not just token deltas.
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 is a sawtooth: steady-state cost per turn is roughly (trigger+floor)/2. Against a 1M-window provider default (~480k average input), a 250k trigger lands near 3.3x fewer input tokens; an aggressive 150k/20k setting near 5.6x. The best case — long tool-heavy sessions where elision drives the floor toward zero — approaches 10x.
Does it edit my live session?
No. 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. 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 — preset.command pipes normalized transcript JSON to any program and applies the edits it returns. The agentic preset uses the same seam: a bounded editor model that may keep, elide, summarize, or defer each item.
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.