Headroom

What it does

Headroom Labs builds Headroom to shrink what a coding agent reads: tool output, logs, JSON, search results and file contents. The package ships several things (a Python and TypeScript library, an OpenAI-compatible proxy, wrappers for agents such as Claude Code and Codex). This page covers the MCP server, which is the `headroom mcp serve` command from the Python package.

The assistant decides when to call it. It hands a large block of text to headroom_compress and gets back a shorter version plus a hash. The original stays in a local store for an hour, so headroom_retrieve can return the full text later if the short one turns out to be missing something. If you also run the proxy, retrieval falls back to the proxy's own store when the hash is not held locally. headroom_stats reports how many tokens the session has saved, including counts from sub-agents that run their own copy of the server.

The source registers a fourth tool the README does not list. Setting HEADROOM_MCP_READ=on adds headroom_read, which reads a file from disk and caches it, then answers repeat reads of an unchanged file with a short marker in place of the whole file. The docs also describe a query option on headroom_retrieve for searching inside an original, but the tool schema in the server source takes only the hash.

What it needs

Install the package with the MCP extra: pip install "headroom-ai[mcp]", or uv tool install "headroom-ai[mcp]" so the headroom command lands on your PATH. Clients such as Codex that do not inherit your shell PATH need the absolute path from command -v headroom. headroom mcp install registers it with Claude Code. Retrieval from the proxy's store needs headroom proxy running separately.

Limits

• Limit Compressed originals kept by the MCP server expire after one hour, and those held by the proxy after 30 minutes unless HEADROOM_CCR_TTL_SECONDS changes it.
• Platform Native wheels cover macOS on Apple Silicon and Linux. The README points Intel Mac users to the Docker install instead.
• Limit headroom_read only appears when HEADROOM_MCP_READ is set to on. It is off by default.
• Not covered It compresses only what the assistant passes to it. Automatic compression of all model traffic needs the separate headroom proxy.
• Cost Each tool call and result counts toward the client's context, so many calls in a long session can show up as a share of usage.
• Limit The ONNX-based content detection and relevance features need AVX2 on x86 hosts and fall back to simpler methods without it.

Who it suits

It suits someone running Claude Code, Cursor or Codex on large logs and JSON who wants the agent to shrink content on demand without routing traffic through a proxy. Everything runs locally and the core tools only transform text the assistant hands them, so the main things to weigh are the usage beacon (switch it off with HEADROOM_BEACON=off) and the optional file-reading tool. If you want every request compressed without the assistant choosing to, the makers point to headroom proxy instead. People on Intel Macs or Python older than 3.11 will need Docker or a newer interpreter.