chopratejas /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
+71
日增长
+1,005
周增长
+4,599
月增长
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
相关报道 (6)
T客邦GitHub 狂攬 4 萬星!Headroom 開源工具幫開發者省下 70 萬美元 API 費,Token 消耗暴降 92%2026-08-01OSCHINA从一张 287 美元账单到 4.4 万 star 的开源传奇:Netflix 工程师如何用 Headroom 为 AI Agent “瘦身” 90% 的 Token2026-06-23CSDN博客Headroom开源工具:最高节省92%Token成本,为AI编程降本增效2026-06-23Pasquale PillitteriHeadroom 在 JSON 上将 AI token 削减最多 95%:诞生于 Netflix 的工具2026-06-20InfoQ.cn砍掉 90% 冗余词元,省下 70 万美元:Netflix 开源工具狙击 AI 账单黑洞2026-06-18view.inews.qq.com狂揽22.2k star!AI智能体上下文压缩工具开源,Token成本直降95%准确率不变2026-06-12
News & coverage (15)
Hacker NewsCompress tool outputs, logs, files, RAG chunks before LLM for 60-95% less tokens▲ 4 · 0 comments · 2026-06-20Hacker NewsA Compression Tool for LLM Reads. Est. 60-95% Fewer Tokens▲ 4 · 0 comments · 2026-05-16Hacker NewsHeadroom – LLM Input Compression▲ 3 · 0 comments · 2026-05-31Hacker NewsShow HN: Headroom (OSS): Cuts LLM costs by 85%▲ 3 · 5 comments · 2026-01-18Hacker NewsTokenMinMaxing▲ 2 · 0 comments · 2026-06-18Hacker NewsHeadroom▲ 2 · 0 comments · 2026-06-17Hacker NewsHeadroom – context optimization layer for tool-using agents▲ 2 · 2 comments · 2026-01-13Hacker NewsShow HN: Headroom – Reversible context compression for LLMs(~60% cost reduction)▲ 1 · 1 comments · 2026-01-15note[20261019] LLM News & FP8 KV Cache for Increasing Inference Headroom2026-10-19alphamatch.aiHeadroom: The Context Compression Layer Your AI Agent Desperately Needs2026-06-11