Context compaction you can undo.

gobstopper.sh · 2026-10-03 · by Long Nguyen ·generic
Gobstopper makes long Claude Code and Codex sessions smaller. A local proxy compacts live requests, and saved sessions get a smaller copy beside the original.

Context compaction you can undo.

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.

Run a session

gobstopper proxy run -- claude

Session

Without GobstopperWith Gobstopper

Point in the session

EarlyHalfwayEnd

claude

Request 20 of 383\~63,920estimated tokens sent with this request

threshold after calibration: \~64,000no proxy: nothing is ever summarized

claude

Request 191 of 383\~327,458estimated tokens sent with this request

threshold after calibration: \~77,154no proxy: nothing is ever summarized

claude

Request 383 of 383\~491,135estimated tokens sent with this request

threshold after calibration: \~82,315no proxy: nothing is ever summarized

claude, through gobstopper proxy

Request 20 of 383\~63,920estimated tokens sent with this request

threshold after calibration: \~64,000summarized 0 times so far

claude, through gobstopper proxy

Request 191 of 383\~38,967estimated tokens sent with this request

threshold after calibration: \~77,154summarized 7 times so far

claude, through gobstopper proxy

Request 383 of 383\~68,581estimated tokens sent with this request

threshold after calibration: \~82,315summarized 10 times so far

claude, through gobstopper proxy

Request 191 of 383\~38,967estimated tokens sent with this request

threshold after calibration: \~77,154summarized 7 times so far

One recorded Claude Code session replayed at the 128,000-token default. Sizes estimate four characters per token.

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

CCClaude CodeCCodexOopencode CCrushAAiderGGoose

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.

1. 01

Preview the cut

Find a Claude Code or Codex session and inspect what a strategy would remove before writing anything. 2. 02

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. 3. 03

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.

1Find2Preview3Copy4Search5Undo

\~/code/lanternshop

$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

$

\~/code/lanternshop

$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

$

\~/code/lanternshop

$gobstopper apply 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

prepared \~/.claude/projects/-Users-sam-code-lanternshop/2d34930a-813b-4c47-a587-51869c4b85f7.jsonl

recovery snapshot: 09ccf7cd7bca78d3273058ee0ea05a59fc5e8ded066099b1ed854b4b443f4080

resume the new session: claude --resume 2d34930a-813b-4c47-a587-51869c4b85f7

reclaimed \~383318 bytes in the prepared fork

$

\~/code/lanternshop

$gobstopper search-snapshot 09ccf7cd7bca78d3273058ee0ea05a59fc5e8ded066099b1ed854b4b443f4080 --query "(fail)" --limit 2

{

"snapshot\_sha256": "09ccf7cd7bca78d3273058ee0ea05a59fc5e8ded066099b1ed854b4b443f4080",

"source\_sha256": "46eef7bc276c128e3938cee1ba8c8a09f18f2305cdb070c8926f553303adbe92",

"matches": \[

{

"record\_index": 2,

"record\_sha256": "51b814676631f07261d42dac69a269bef2ec3f8d8dc78f7e2a0a6725d7ba0d6c",

"record\_bytes": 4369,

"match\_count": 9

},

{

"record\_index": 8,

"record\_sha256": "516432ae6ac7e39801096b8031101981993146176165efdb0f88d1f01ebad0a9",

"record\_bytes": 4369,

"match\_count": 9

}

\],

"matched\_records": 40,

"unsearchable\_records": 0,

"truncated": true

}

$

\~/code/lanternshop

$gobstopper undo 5f0c2a9e

restore snapshot 09ccf7cd7bca78d3 — 952699 bytes, session 5f0c2a9e-7b1d-4c3e-9a55-2d8e61f0b4a7

restored copy \~/.claude/projects/-Users-sam-code-lanternshop/2704bb52-109d-47fb-86ce-a5004b015748.jsonl

claude --resume 2704bb52-109d-47fb-86ce-a5004b015748

$

Step 1 of 5

Preview a saved session

gobstopper detect
gobstopper plan <session> --trigger 250000

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.

  • cache reads (context re-sent)
  • new input (not cached)

    • Gobstopper, tail 061 of 89 solved

    84.3M

    Claude Code, no proxy60 of 89 solved

    118.6M

    Gobstopper, tail 40 (old default)59 of 89 solved

    118.5M

    040M60M80M120M

    input tokens, all 89 tasks

    Bar chart of total input tokens over 89 Terminal-Bench tasks. Gobstopper, tail 0: 84.3 million, 61 solved. Claude Code, no proxy: 118.6 million, 60 solved. Gobstopper, tail 40 (old default): 118.5 million, 59 solved. Cache reads make up most of each bar.

    Total input over 89 tasks. Almost all of the difference is cache reads, the context resent on every step: 68.7M vs 102.6M. New input and output were about equal.Terminal-Bench 2.1 · 89 tasks · one trial per arm · Claude Code 2.1.283 with GLM 5.3 Flash via Vercel AI Gateway · Gobstopper v0.7.2, 45,000-token threshold (default 128,000) · September 27–28, 2026 · 21 of 89 tail-0 trials may have run an earlier build

    Show the numbers

    | Total input tokens over 89 tasks, provider-reported| 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 75 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 1. Your coding agent resends everything. 2. Every step. The whole session. 3. Long sessions pay for it again. 4. Gobstopper sits in between. 5. Keep the start. Keep the last three. 6. Long printouts out. Files stay on disk. 7. No model writes the summary. 8. Same prefix, so the cache keeps matching. 9. Tasks solved: 61 vs 60. 10. Input tokens sent: 29% fewer. 11. Almost all of it: cache reads. 12. Our old default cost more. 13. So v0.7.3 changed the default. 14. Your session files are never edited. 15. One trial. One model. Read the limits. 16. gobstopper proxy run -- claude

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

    Read the launch post.

    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.

    Runs on

  • macOS
  • Linux
  • Windowspartial

    • Then run one Claude Code session through the proxy: `gobstopper proxy run -- claude`.

    Latest tagged release: v0.8.5.

    Built-in inspection makes no model call. An optional remote scorer receives selected transcript text; trusted plugins run your code. Installation and command reference.

    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.

  • Excalibur (xcb)xcb.shRoutes coding tasks across the Claude, Codex, and Devin plans you have
gobstopper.sh · 1 images · 1 videos · 30 links

Comments (0)

No comments yet