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.

★ 79,731⑂ 6,243👁 213⑃ 3,372● 1,364▤ 178
PythonApache-2.0Created 2026-01-07docs.headroomlabs.ai/docs
Download: Release v0.44.0Release-0.44.0 ↓0.44.02026-11-10
+71
Daily
+1,005
Weekly
+4,599
Monthly
79,731
stars
6,243
forks
213
watchers
3,372
prs
1,364
issues
178
releases

README

Quickstart ·
  Headroom for Teams ·
  Install ·
  Proof ·
  Agents ·
  Docs ·
  Discord ·
  llms.txt


AI agents / LLMs: read /llms.txt here, or fetch
the live index ·
full docs blob.





Headroom (headroom-ai on PyPI and npm) compresses everything your AI agent
reads — tool outputs, logs, RAG chunks, files, and conversation history — before
it reaches the LLM. Same answers, fewer input tokens. Measured: 21–57% fewer
input tokens on four agent scenarios, 90%+ on repeated JSON arrays and log
lines, little on prose (Proof). Compression
runs on your machine; no prompt or file content is sent anywhere to be compressed.

 Start here

My app calls an LLM (Python, LangChain, LiteLLM, Agno, Strands):

bash
pip install headroom-ai


python
from headroom import compress

result = compress(messages, model="gpt-4o")   OpenAI or Anthropic message dicts
client.chat.completions.create(model="gpt-4o", messages=result.messages)


No API key, no model download, in-process. Set HEADROOM_OFFLINE=1 for a
zero-network run. Tool and assistant messages are compressed; user messages are
left alone unless you pass compress_user_messages=True.
FastAPI example ·
API reference.
TypeScript apps: npm install headroom-ai plus the proxy
(pip install "headroom-ai[proxy]", headroom proxy --port 8787); the npm SDK
sends messages to it. TypeScript quickstart

I run coding agents (Claude Code, Codex, Cursor, Copilot, OpenCode, Aider):

bash
uv tool install --python 3.13 "headroom-ai[all]"
headroom wrap claude


Zero code changes. Agent compatibility ·
Proxy


  



  
  10,144 → 1,260 tokens. The same FATAL found.


 What it does

- Library — compress(messages) in Python or TypeScript, inline in any app.
- Proxy — headroom proxy --port 8787, zero code changes, any language.
- Agent wrap — headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|droid|zcode in one command; undo with headroom unwrap .
- MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client.
- Cross-agent memory — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup.
- headroom learn — mines failed sessions and writes corrections to CLAUDE.local.md (default, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md.
- Output token reduction — trims what the model writes back, not only what you send. See below.
- Reversible (CCR) — originals are cached locally and retrieved on demand.

 How it works


 Your agent / app
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
        │   prompts · tool outputs · logs · RAG results · files
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (runs locally — your data stays here)  │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
   

Top issues

Discussions

Latest release

Release v0.44.0 v0.44.0 2026-11-10
0.44.0 (2026-11-09)


 ⚠ BREAKING CHANGES

 packaging: keep PyTorch extras out of all (4067)

 Features

 pipeline: say whose request an OutcomeSnapshot is (4698) (a2bcbd1)
 providers: add Hermes agent wrap support (934) (7877241)
 proxy/model-router: add shadow mode (HEADROOM_MODEL_ROUTER_LOG_ONLY) (2395) (861ef95)
 proxy: add lossless /v1/compress mode and detect provider by wire shape (4617) (33f067a)
 proxy: expose per-request cost_usd in /stats recent_requests (1079) (1565) (84cedbf)
 proxy: expose shared Redis store availability in /health and /metrics (4578) (602ca65)
 proxy: give turn 

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON