Headroom
Local context compression for agents: tool outputs, logs, files and RAG chunks shrink before reaching the LLM. Proxy, CLI, library and MCP
Install
uv tool install --python 3.13 "headroom-ai[all]"Or pip install "headroom-ai[all]". Check with headroom doctor.
This is third-party code. Review the repository files before installing.
What it does
Headroom sits between the agent and the model provider and compresses what the agent reads: JSON, code, logs and prose, each with its own compressor. Originals are cached locally and the model can fetch the full text through the headroom_retrieve tool. The headroom wrap command starts the proxy and launches the agent (Claude Code, Codex, Aider, OpenCode, Goose and others) routed through it, and headroom unwrap reverts it. There is an MCP server with compress, retrieve and stats tools, shared memory across agents, a headroom learn command that mines failed sessions and writes corrections into CLAUDE.md or AGENTS.md, and optional output token reduction.
Who it is for. For developers who work heavily with agents and want to spend fewer tokens on long tool outputs.
Good fit when
- The agent drowns in long logs, JSON responses and search results
- You want to cut API costs without changing code
- You need shared memory between Claude Code and Codex
- You are building an LLM app and want to compress messages with a library
Not a fit when
- Your context is already short and dense prose, so gains will be small
- You cannot route provider traffic through a local proxy
Example request
Show how many tokens Headroom saved in this sessionLimitations
Savings depend heavily on content: repetitive JSON and logs compress well, prose barely does. The CLI ships only in the PyPI package; the npm package is a TypeScript library. By default wrap registers Serena at user scope, which you can skip with --code-memory none. Headroom itself runs locally, but the model provider APIs it proxies may be region-restricted.
How to disable. Run headroom unwrap <tool> to remove the wrapper, then uninstall with uv tool uninstall headroom-ai or pip uninstall headroom-ai.
MCP
- Transport
- stdio
- Authentication
- not required
Security check
- All agent traffic to the model provider, including API keys, passes through the local proxy
- wrap changes agent configuration and registers extra MCP servers
- learn writes changes into CLAUDE.md and AGENTS.md
README in short
The README covers four modes: the compress library for Python and TypeScript, the headroom proxy, the headroom wrap agent wrapper and an MCP server. Compression uses a content-type router with separate compressors for JSON, code and text, plus a local cache of originals. It includes reproducible savings and accuracy benchmarks, an agent compatibility table and output reduction settings. Apache 2.0 licensed.
FAQ
Is prompt content sent anywhere to be compressed?
No, per the README compression runs on your machine and originals are cached locally.
Will compression hurt answer quality?
The authors publish runs on GSM8K, TruthfulQA, SQuAD and BFCL with no detectable accuracy loss; the methodology is in the docs.
Related
Open-source personal AI assistant on your own machine: answers in Telegram, Slack, Discord and WhatsApp, extended with skills and plugins
A self-improving agent from Nous Research with a TUI, messaging gateway, cron jobs and skills it writes itself
An open source coding agent for the terminal and desktop with build and plan modes
Open prompt library with a Claude Code plugin, MCP server and CLI: search, fetch and improve prompts and skills from an agent