Save tokens while preserving context.
Gobstopper replaces the compaction built into Claude Code and Codex with a local proxy that compacts more often. Your agent's full history stays on your machine.
macOS
curl -fsSL https://gobstopper.sh/install.sh | shcargo install --git https://github.com/hraness/gobstopper gobstopper --locked
Linux
curl -fsSL https://gobstopper.sh/install.sh | shcargo install --git https://github.com/hraness/gobstopper gobstopper --locked
Windows
irm https://gobstopper.sh/install.ps1 | iexcargo install --git https://github.com/hraness/gobstopper gobstopper --locked
btw, 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 saves tokens while preserving context. Compaction is the step your harness runs to squeeze a long conversation into the context window. Gobstopper replaces the compaction built into Claude Code and Codex. It proxies API requests, compacts more often to save tokens, and writes the full history to a local database your agents can search. On Terminal-Bench 2.1 it used 29% fewer tokens than Claude Code's built-in compaction and solved the same number of tasks.
Ask your agent to set it up: gobstopper.sh
Ben Guo
While you work
Keep the recent work in view.
Start Claude Code through Gobstopper. Small requests pass through unchanged; large ones keep the system prompt, the first task, and the newest turns word for word while older turns become a summary.
gobstopper proxy run -- claudeThe proxy starts on a free local port and stops when the agent exits. Its default threshold is 128,000 estimated tokens. It uses local rules to summarize, with no extra model call, and leaves your session files unchanged.
Claude Code and Codex routing is live-checked. Other agents need a configurable provider address; OpenAI Chat Completions support is tested with synthetic histories. Proxy setup and options.
Saved sessions
Try a smaller copy. Keep a way back.
Preview the cut
Find a Claude Code or Codex session and inspect what a strategy would remove before writing anything.
Keep the original
Compaction creates a separate copy and saves the original bytes in a local vault. Search that vault or prepare a restored copy when you need an older detail.
Check before resuming
Copy checks cover record links, order, and tool-call pairs. They cannot guarantee provider resume, retention of every task fact, or what you will be billed.
gobstopper detect
gobstopper plan <session> --trigger 250000Usage 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 checks GitHub once a day for a new release and installs it only after verifying it; aicharts update disable turns that off. aicharts usage.
Terminal-Bench 2.1
About as many tasks solved, 29% fewer tokens sent.
One recorded run: Gobstopper at tail 0 resolved 61 of 89 tasks against 60 with no proxy, within single-trial noise, and sent 29% fewer input tokens. The benchmarks page has the setup and limits.
29% fewer input tokens
29% fewer input tokens in one benchmark
Gobstopper, tail 0 vs Claude Code, no proxy · about as many tasks solved, within single-trial noise
- cache reads (context re-sent)
- new input (not cached)
Show the numbers
| Arm | Solved of 89 | Total input | Cache reads | New input |
|---|---|---|---|---|
| Gobstopper, tail 0 | 61 | 84.3M | 68.7M | 15.6M |
| Claude Code, no proxy | 60 | 118.6M | 102.6M | 15.9M |
| Gobstopper, tail 40 (old default) | 59 | 118.5M | 98.2M | 20.3M |
These results cover one model and setup; they do not establish task-quality or billing improvements for other agents. Setup, statistics and downloads.
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
- Linux
- Windowspartial
Then run one Claude Code session through the proxy: gobstopper proxy run -- claude.
Latest tagged release: v0.8.10.
Built-in inspection makes no model call. An optional remote scorer receives selected transcript text; trusted plugins run your code. Installation and command reference.
Questions
Before you install.
Which agents can use the proxy?
Any agent that lets you set a custom provider address and uses Anthropic Messages, OpenAI Responses, or OpenAI Chat Completions. Claude Code and Codex routing is live-checked; Chat Completions is contract-tested on synthetic histories. File commands read Claude Code and Codex session formats.
What if I need something the smaller copy 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. Keep backups of the vault: recovery depends on your storage.
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 model and client's supported window. The budget expires by time or request count. Optional adaptive rescue temporarily raises the threshold after repeated reads of unchanged evidence the proxy removed. Gobstopper also keeps selected original tool results and images through repeated compactions. These controls reduce evidence loss; they cannot guarantee task progress. 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. Codex launch requires a healthy proxy. Existing sessions using a fixed proxy URL still depend on that listener. See recovery and fallback requirements.
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. Managed service changes wait for active inference to finish. During inference, Gobstopper requests idle-sleep prevention; closing a lid or forcing sleep can override it. 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.
