Headroom MCP
Local context compression for agents: tool outputs, logs, files and RAG chunks shrink before reaching the LLM. Proxy, CLI, library and MCP
- 78,172 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- 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
Install
- Works in
Manual install
uv tool install --python 3.13 "headroom-ai[all]"Or pip install "headroom-ai[all]". Check with headroom doctor.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- 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
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 sessionMCP
- Transport
- stdio
- Authentication
- not required
Limitations
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.
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.
Discussion
No questions or reviews yet.
Related
MCP serversLocal persistent memory for coding agents: hooks record every session, and Claude Code, Codex or Cursor recall past decisions through 54 MCP tools
A local context layer for coding agents: it understands the task, routes and compresses context and tracks the cost
A skill that cuts an agent's prose output, plus a local proxy that compresses what the agent reads
Long-term memory for agents: a remote MCP server, plugins for Claude Code, Cursor and Codex, and an API for your own apps
An MCP server that keeps large tool output out of the agent's context window and stores session memory in SQLite
A local context store for coding agents that captures project knowledge and reuses it across Codex, Claude Code and OpenCode
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.