Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Headroom (headroom-ai)
Compress tool outputs, logs, JSON and chat history before each LLM call, so the model sees fewer input tokens and the same facts. Runs in-process, in Python, with no API key and no model download. Originals are cached locally and retrievable.
Measured: 21–57% fewer input tokens on four agent scenarios, 90%+ on repeated JSON arrays and log lines, little on prose. Numbers and how to reproduce them: https://docs.headroomlabs.ai/docs/benchmarks and the "Proof" section of https://github.com/headroomlabs-ai/headroom
Use it from a Python app that calls an LLM
pip install headroom-ai
from headroom import compress
result = compress(messages, model="gpt-4o") # OpenAI or Anthropic message dicts
result.messages # same shape as the input, fewer tokens
result.tokens_before, result.tokens_after, result.tokens_saved
Pass result.messages to your existing client call instead of messages.
Nothing else changes. Error lines, stack traces, first and last items and
statistical outliers are kept; repeated and low-information items are dropped.
Zero-network check, no provider key needed:
HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"
Prints on the order of 20000 -> 95 FATAL kept: True. HEADROOM_OFFLINE=1
blocks every connection Headroom would make on its own: the update check, model
and pricing-table downloads, and the anonymous usage beacon the proxy and MCP
server send by default (HEADROOM_BEACON=off turns off only the beacon).
FastAPI example with a POST /chat endpoint:
https://docs.headroomlabs.ai/docs/fastapi
Use it around a coding agent (no code changes)
uv tool install --python 3.13 "headroom-ai[all]" # CLI in its own env; pip install "headroom-ai[proxy]" also works
headroom wrap claude # also: codex, grok, copilot, cursor, aider, opencode, cline, continue, goose, openhands, openclaw, vibe, omp, zcode
headroom proxy --port 8787 # or run the proxy and point any client at it
Other entry points
- OpenAI, Anthropic, LiteLLM, LangChain, Agno, Strands, CrewAI, AutoGen adapters: https://docs.headroomlabs.ai/docs (Integrations)
- MCP server (
headroom_compress,headroom_retrieve,headroom_stats): https://docs.headroomlabs.ai/docs/mcp - TypeScript SDK (
npm install headroom-ai, needs the proxy running): https://www.npmjs.com/package/headroom-ai - Full docs index for agents: https://docs.headroomlabs.ai/llms.txt
- Source and issues: https://github.com/headroomlabs-ai/headroom
Extras: [proxy] adds the HTTP proxy and headroom wrap, [mcp] the MCP
server, [ml] the Kompress text model (torch), [all] everything. The base
install is enough for compress(). Requires Python 3.11+.
Apache 2.0. The import and CLI name is headroom; the PyPI distribution named
headroom is a different project.