Gobstopper
Install
Theme
Appearance

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.

Install GobstopperSee the benchmark

Free and open source · MIT or Apache-2.0 · Latest release: v0.8.10

Past the threshold, Gobstopper keeps the system prompt, your first task, and the last three turns word for word, turns the older turns into one summary, and writes the whole conversation to a local vault your agents can search.

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.

RyaanSoftware Engineer, BandLab

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

How it works

Keep the recent work in view.

Past the threshold, the proxy keeps the newest turns word for word and summarizes older ones with local rules, no extra model call.

Your agentClaude Code, Codex, and moreGobstopper proxyon 127.0.0.1, no model callModel APIAnthropic, OpenAI, a gatewayLocal vaultthe full history, on your diskevery requestresponsescompacted requestresponsesfull historysearch, undo
Requests leave your agent as usual. Past the threshold, Gobstopper rewrites the request before it reaches the model, and every turn it summarized stays readable in the vault.

Works with

Start your agent through it.

Claude Code and Codex start through the proxy with one command; opencode, Crush, Aider, and Goose point at its local address.

$ gobstopper proxy run -- claude
2026-09-30T00:05:54.301Z gobstopper proxy: http://127.0.0.1:61631, threshold 128000 tokens, threshold_1m 256000 tokens, keep_recent 3, keep_tail_percent 0, carry_max_chars 24000, calibrate on
agent sees ANTHROPIC_BASE_URL=http://127.0.0.1:61631
2026-09-30T00:05:54.305Z gobstopper proxy: 0 requests, 0 compacted, 0 reused a compacted prefix
Claude CodeCodexopencodeCrushAiderGoose

Saved sessions

Try a smaller copy. Keep a way back.

Preview what a strategy would cut from a saved session, then write a separate copy and keep the original in a local vault.

$ 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 items
Real output from a release build on September 29, 2026, against a synthetic Claude Code session; the project and user are made up.

Read how saved sessions work.

Terminal-Bench 2.1

29% fewer input tokens, as many tasks solved.

Claude Code through Gobstopper solved 61 of 89 tasks against 60 with its built-in compaction, on 29% fewer input tokens.

fewer input tokens
29%84.3M against 118.6M
tasks solved
61 of 89Gobstopper, tail 0
tasks solved
60 of 89Claude Code, no proxy
fewer cache reads
33%68.7M against 102.6M

Terminal-Bench 2.1, with and without Gobstopper. 89 tasks · one trial per arm · Claude Code 2.1.283 with GLM 5.3 Flash via Vercel AI Gateway · Gobstopper v0.7.2 at a 45,000-token threshold · September 27–28, 2026. Setup, statistics, and downloads · How Gobstopper measures.

Film

Watch it in 34 seconds.

Captions carry every line, and nothing plays until you press play.

The film is also available as text below.

Read the film's text
  1. On every step, your coding agent resends the whole session.
  2. That includes output that mattered once.
  3. Gobstopper
  4. Gobstopper trims the old printouts before they reach the model.
  5. In one recorded benchmark, it solved about as many tasks and sent fewer tokens.
  6. Your session files are never edited.
  7. 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.

macOS

Terminal
curl -fsSL https://gobstopper.sh/install.sh | sh
Apple 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. Installation and command reference.

Latest tagged release: v0.8.10.

Limits
  • The proxy needs curl 8.3 or newer. Built-in compaction makes no model call; an optional remote scorer receives selected transcript text, and plugins you install run your code.
  • 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.

Questions

Before you install.

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, 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.

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.

Other tools from our studio

Tools for Token Maximalists