Token-budget compression layer wrapped around Claude Code and Codex sessions

What they did

They installed the headroom-ai package and used `headroom wrap claude` and `headroom wrap codex` to route existing agent sessions through the local compression proxy on port 8787, without changing any application code. They also registered the MCP server so the agent could call `headroom_compress`, `headroom_retrieve`, and `headroom_stats` directly when it wanted to shrink a large tool output or pull back an original via the reversible CCR cache. To keep the agent's own notes tidy, they paired this with Serena's semantic code tools so symbol lookups and edits stayed precise instead of dumping whole files into context. They ran a before/after comparison on a long CI log and a large JSON API response, checking that the FATAL error line and specific field values survived compression byte for byte, and reviewed `headroom_stats` to see token savings per session.

How it went

Token usage on log-heavy and JSON-heavy turns dropped substantially, with the critical error line still present after compression. The wrap/unwrap flow was easy to reverse, and the MCP tools let the agent compress on demand rather than always. Setup was quick but required reading the docs to get the proxy port and MCP registration right.

Worth knowing

Compression quality depends on content type; prose and code benefit less than logs and JSON. The reversible cache is local, so retrieval only works on the same machine. Wrapping agents changes how sessions launch, so teams should test unwrap before rolling out. No benchmark numbers were independently verified here.

Wiring

Install with pip or npm (`headroom-ai`). Start the proxy with `headroom proxy --port 8787` and point the agent at it, or use `headroom wrap claude|codex` for a one-command launch that can be undone with `headroom unwrap <tool>`. Register the MCP server in the agent's MCP config so `headroom_compress`, `headroom_retrieve`, and `headroom_stats` are available as tools. Originals are cached locally by the CCR layer for retrieval. Serena runs as a separate MCP server exposing semantic symbol tools; both servers can be listed in the same MCP config so the agent picks compression for bulky outputs and Serena for code navigation.

Try it yourself

Set up Headroom in this repo: install headroom-ai, start the local proxy on port 8787, and wrap my Claude Code and Codex sessions. Register the MCP server so the agent can call headroom_compress, headroom_retrieve, and headroom_stats. Then take one large CI log and one large JSON response, compress them, and confirm the FATAL line and key fields survive byte for byte. Report token savings from headroom_stats and show me how to unwrap.