Context compaction proxy
Spend 29% fewer tokens on every long session.
Gobstopper is an intelligent compaction proxy for Claude Code and Codex. It sits between your agent and the API, compacts more often than the built-in step, and keeps the full conversation history on your machine for your agents to search.
Free and open source · MIT or Apache-2.0 · Latest release: v0.8.10
$ gobstopper plan 5f0c2a9e --strategy elide --trigger 100000
claude_code 5f0c2a9e-7b1d-4c3e-9a55-2d8e61f0b4a7 (idle)
context: 130060 -> ~39818 tokens (saves ~90242)
prefix: 83 tokens cached
strategy: elide
context 130060 tokens exceeds trigger 100000; eliding 64 of 140 stale tool outputs
elide 64 itemsbtw, like a week in, Gobstopper is absolutely kicking ass. I’m using the higher context scope for my orchestration agent, and then all workers on the default, and the token savings are insane and the quality of task completion is unchanged.
Gobstopper replaces the compaction built into Claude Code and Codex. It proxies the API, compacts more often, and keeps the full history in a local database your agents can search. On Terminal-Bench 2.1 it used 29% fewer tokens than the built-in step and solved the same number of tasks.
Ben Guo
Ask your agent to set it up: gobstopper.sh
The idea
Compact more often. Keep everything.
Every request from a coding agent carries the whole session, including output that mattered once. Gobstopper compacts earlier and more often than the built-in step, so the model reads less on every step, and the full history stays on your machine.
How it works
Keep the recent work in view.
Start your agent through Gobstopper. Small requests pass through unchanged. Past the threshold, the proxy keeps the system prompt, the first task, and the newest turns word for word, and summarizes the older turns with local rules, with no extra model call.
gobstopper proxy run -- claudeSession
Point in the session
Request 191 of 383~38,967estimated tokens sent with this request
threshold after calibration: ~77,154summarized 7 times so far
The proxy starts on a free local port and stops when the agent exits. Its default threshold is 128,000 estimated tokens. Session files on disk stay unchanged.
Claude CodeCodexopencodeCrushAiderGoose
Claude Code and Codex start through it with one command. opencode, Crush, Aider, Goose, and any other client of the Anthropic Messages, OpenAI Responses, or OpenAI Chat Completions dialect point at its local address. Proxy setup and options.
Preview the cut
Find a Claude Code or Codex session and see what a strategy would remove before writing anything.
Keep the original
Compaction writes a separate copy and saves the original bytes in the local vault. Search the vault or restore the original when you need an older detail.
Check before resuming
Every copy is checked for record links, order, and tool-call pairs before you resume it.
$gobstopper detect
PROVIDER SESSION STATE CTX TOKENS LIFETIME IN PATH
claude_code 5f0c2a9e-7b1d-4c3e-9a55-2d8e61f0b4a7 idle 130060 9027000 ~/.claude/projects/-Users-sam-code-lanternshop/5f0c2a9e-7b1d-4c3e-9a55-2d8e61f0b4a7.jsonl
gobstopper detect
gobstopper plan <session> --trigger 250000Terminal-Bench 2.1
29% fewer input tokens, as many tasks solved.
Claude Code through Gobstopper at tail 0 and a 45,000-token threshold solved 61 of 89 tasks against 60 with its built-in compaction, and sent 29% fewer input tokens: 84.3M against 118.6M. Most of the gap is cache reads, the context resent on every step.
Usage history
Measure what your agents sent.
The installer adds aicharts beside Gobstopper and turns on its local usage history: your token use by day, agent, provider, and model, kept on this computer and never uploaded.
gobstopper usage
gobstopper usage report --days 7 --csvgobstopper usage reads the same aicharts record across every agent, including ones that never pass through the proxy, and agents read it back through the read-only aicharts mcp tools. aicharts usage.
Film
Watch it in 34 seconds.
No narration. Captions carry every line. The film never plays until you press play.
The film is also available as text below.
Read the film's text
- On every step, your coding agent resends the whole session.
- That includes output that mattered once.
- Gobstopper
- Gobstopper trims the old printouts before they reach the model.
- In one recorded benchmark, it solved about as many tasks and sent fewer tokens.
- Your session files are never edited.
- Ask your agent: “Install Gobstopper from gobstopper.sh”
Terminal-Bench 2.1 · 89 tasks · 1 trial per arm · GLM 5.3 Flash · 45K threshold (default 128K) · Sept 27–28, 2026. Resolution is within single-trial noise. Cost is provider-reported, metered through Vercel AI Gateway, for this model, at a 45K threshold (default 128K).
Install
Start with one session.
Each installer downloads the latest release for your platform, checks its SHA-256, and installs it for your user only. The proxy needs curl 8.3 or newer.
macOS
Terminal
curl -fsSL https://gobstopper.sh/install.sh | shApple silicon
Build from source (Rust 1.85+)
cargo install --git https://github.com/hraness/gobstopper gobstopper --locked
- macOS
- Linux
- Windowspartial
Then run one session through the proxy: gobstopper proxy run -- claude.
Latest tagged release: v0.8.10.
Built-in compaction makes no model call. An optional remote scorer receives selected transcript text; plugins you install run your code. Installation and command reference.
Limits
- The Terminal-Bench 2.1 result is one trial per arm with one model, GLM 5.3 Flash, at a 45,000-token threshold rather than the 128,000 default; the two-task gap in tasks solved is within single-trial noise, and 21 of the 89 tail-0 trials may have run an earlier build.
- Claude Code and Codex routing is checked against live sessions; OpenAI Chat Completions routing is tested against synthetic histories.
- On Windows the proxy works; the vault, watch, and provider hooks need macOS or Linux.
- The vault lives on your disk and is only as safe as your backups. Copy checks cover record links, order, and tool-call pairs; they cannot promise that a provider resumes the copy or that a summary kept every fact.
Compare
How it compares.
Two side-by-side pages: the compaction built into Claude Code, and CliffCompaction, the Python proxy whose summary rule Gobstopper ports to Rust.
Which agents can use the proxy?
Claude Code and Codex start through it with one command. Any other agent that lets you set a custom provider address and speaks Anthropic Messages, OpenAI Responses, or OpenAI Chat Completions, such as opencode, Crush, Aider, and Goose, points at the proxy's local address. File commands read Claude Code and Codex session formats.
What if I need something the summary left out?
Before writing a separate Claude Code or Codex copy, Gobstopper archives the original and prepared bytes. Search the local vault for a missing record, read its saved text, or run gobstopper undo to prepare a restored copy with a new session identity.
Does it edit my live session?
The proxy changes outgoing requests and leaves session files unchanged. File commands prepare separate copies. Gobstopper does not trigger Claude Code's or Codex's own compaction and does not edit session files in place. Automatic provider compaction stays disabled.
What if an agent keeps rereading the same files?
You or the agent can reserve a larger context for a difficult phase, within the window the model and client support. The budget expires by time or request count. Optional adaptive rescue raises the threshold for a while after repeated reads of unchanged output the proxy removed, and Gobstopper keeps selected original tool results and images through repeated compactions. See context budgets and retention.
What happens if the proxy stops responding?
Request and compaction deadlines limit stalls, while logging and metrics run in background workers. gobstopper proxy launch --client claude checks readiness before opening Claude Code and can start directly with its official provider when the configuration permits. See recovery and fallback.
Can it start automatically and keep my laptop awake?
Run gobstopper proxy install to start a user service at login and restart it after a process exit. Service changes wait for active inference to finish, and during inference Gobstopper asks the system not to idle-sleep. Local session metrics are available through gobstopper data metrics. See startup and local visibility.
When should I use built-in compaction instead?
Use your agent's built-in /compact when you want a model-written summary without another tool. Gobstopper adds previews and archived originals for saved sessions, plus a proxy that applies local rules without a model call. See the Claude Code comparison or the CliffCompaction comparison.