What is Headroom?
Headroom (headroom-ai on PyPI and npm) compresses what your AI agent reads, including tool outputs, logs, RAG chunks, files and conversation history, before it reaches the LLM. The project's stated goal is the same answers with fewer input tokens. Compression runs on your machine, and no prompt or file content is sent anywhere to be compressed.
There are several ways to use it. In an app, compress(messages) runs in Python or TypeScript, inline in any app, with no API key and no model download. A proxy started with headroom proxy needs zero code changes and works with any language. A wrap command covers coding agents such as Claude Code, Codex, Cursor and Aider, and an MCP server offers compress, retrieve and stats tools to any MCP client.
Compression is reversible: originals are cached locally and retrieved on demand. By default tool and assistant messages are compressed and user messages are left alone. The README reports measured savings on four agent scenarios and says prose compresses little, so results depend on the workload.
Key capabilities
- Library Compress(messages) in Python or TypeScript.
- Proxy Zero code changes, any language.
- Agent wrap One command for supported coding agents.
- MCP server Compress, retrieve and stats tools.
- Reversible storage Originals cached locally for retrieval.
Where Headroom fits
- Cutting token use from tool-heavy agent runs
- Compressing logs and repeated JSON before a model call
- Adding compression to an app with one function call
- Routing existing clients through a local proxy
Install
pip install headroom-aiReviews of Headroom
Be the first to share your experience with Headroom.
Write a review
Loading review form…
Alternatives to Headroom
CogneeCognee is a free, open-source AI memory platform that turns documents, code and conversations into a knowledge graph with vector retrieval for agents.OOmniRouteOmniRoute is an MIT-licensed AI gateway by Diego Souza that routes requests across model providers through one endpoint, with a dashboard and API keys.PPrivateGPTPrivateGPT is an open-source backend API for self-hosted AI apps, with messaging, document retrieval, tools and database access over local inference servers.