headroom

Headroom compresses what an AI agent reads, including tool outputs, logs, RAG chunks, files and conversation history, before it reaches the model. A content router picks a specialised compressor for each type (JSON, source code via the AST, or prose via a small local model), and the originals are cached locally so the model can retrieve the full text when it needs it. Compression runs on your machine; content is not sent anywhere to be compressed.

It is useful wherever context size drives cost or quality: coding agents reading long logs and test output, agents calling APIs that return large JSON, and RAG pipelines. The project's own figures are about 20% fewer tokens for coding agents and 60–95% for JSON-heavy content. You can use it as a Python or TypeScript library, as a local proxy with no code changes, as an MCP server, or by wrapping an agent such as Claude Code, Codex, Cursor or Aider with a single command. It also offers cross-agent memory and a `learn` command that turns failed sessions into instructions in files such as CLAUDE.md or AGENTS.md.

Getting started: install the CLI with `uv tool install --python 3.13 "headroom-ai[all]"` or pip, then run `headroom wrap claude` (or another agent) or `headroom proxy --port 8787`. `headroom doctor` checks the setup and `headroom dashboard` shows live savings.