AI agents accumulate stale tool results — file reads, web fetches, bash outputs — in their context window. Every one sits there for the entire conversation, consuming tokens and degrading quality. The standard fix is auto-compaction: wait until full, then drop content indiscriminately.

Context Surgeon gives the agent three operations — evict, replace, and restore — so it can manage its own context. It works as a transparent local proxy that intercepts API requests, assigns IDs to content blocks, and applies eviction directives before forwarding. The agent calls the tools via bash. The proxy is ephemeral: starts with your CLI session, dies when it ends.

The interesting part is that agents naturally start managing their own context without much prompting. In testing, the agent decided on its own to evict old research results before starting an implementation phase.

Works with Codex CLI and Claude Code.

Install: npm install -g context-surgeon Usage: context-surgeon codex