Headroom: Shrink what your AI agent reads so it uses fewer tokens

What it does

Headroom sits between your app or agent and the AI model. A router detects what kind of content is coming in, such as JSON, source code or plain prose, and picks a matching compressor to shorten it. The creators say compression runs on your machine and no prompt or file content is sent elsewhere to be compressed. Originals are kept locally, so the model can ask for the full text back with headroom retrieve.

How to use it

Input → action → output: run headroom wrap claude (or codex, cursor, aider and others) and your agent session routes through a local proxy that trims tool outputs, logs and history before they are sent. Developers can instead call compress(messages) inside a Python or TypeScript app, run headroom proxy on port 8787, or use it as an MCP server (a way to plug tools into an AI assistant). headroom unwrap undoes the wrap.

Common use cases

• Wrap a Claude Code session and let long build logs be shortened before the model reads them, with the originals kept on disk.
• Pass a chat history full of JSON search results through compress() in a Python app and send a shorter message list to the model.
• Run headroom savings on your own traffic to see how many tokens it would remove for your workload.