headroomlabs-ai /headroom
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
+39
日增长
+538
周增长
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
#4613[BUG] Proxy leaks compression-executor threads (image OCR?), pinning cores.6 comments · 2026-11-02#4433[BUG] security-model.mdx says an unsafe x-headroom-base-url override is "ignored", but the proxy routes answer 4006 comments · 2026-10-22#3563[BUG] CCR recovery JSON re-offloaded through Codex functions.exec wrapper; named retrieval exemption passes6 comments · 2026-09-12#3187[FEATURE] please add wrap support for prime-agent6 comments · 2026-08-21#2649[FEATURE] Pre-upstream context limit guard — hard-cap input tokens to avoid upstream 400 + client retry storm6 comments · 2026-07-29#748[FEATURE] One consolidated `headroom uninstall` command + document teardown in --help and README6 comments · 2026-06-08#709[BUG] Proactive context expansion injects stale CCR contexts in fast agentic sessions6 comments · 2026-06-06#975[FEATURE] headroom wrap support for Kilo Code (VS Code, CLI, Cloud)5 comments · 2026-06-14
Discussions
#4676RFC: one label set for request attribution (project, client, host, …) instead of one axis per dimension0 comments · 2026-11-07#4668Headroom as a baseline in a study on learned field projections for agent tool outputs0 comments · 2026-11-06#4612Measured byte-level savings on Windows: tool output -71.1%, path list -92.0%, build log +0.7%0 comments · 2026-11-02#4483Headroom with rtk 1.00 comments · 2026-10-25#4439Question about MCP-only mode in Codex Desktop: Who evaluates the need for compression and on what basis?1 comments · 2026-10-23#4312Any plan to add support for Mimocode Desktop for Windows?0 comments · 2026-10-20#3961OpusBar: a macOS menu bar app for Claude Code and Codex usage, limits and waiting sessions0 comments · 2026-10-04#3922README idea: HVTrust badge linking to Headroom's independent trust profile0 comments · 2026-10-02
Latest release
Release v0.44.0 v0.44.0 2026-11-100.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