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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs(readme): lead with two front doors and one measured savings claim (#4530)
Tejas Chopraabed065ed3fa
diff --git a/README.md b/README.mdindex 7880d3ba4..a5b042732 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@<div align="center">-<img src=".github/assets/hero.svg" alt="Headroom — the context compression layer for AI agents. A 55,957 token agent prompt compresses to the 24,340 tokens actually sent to the model, and the FATAL line at item 67 survives byte for byte." width="880">+<img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/.github/assets/hero.svg" alt="Headroom — the context compression layer for AI agents. A 55,957 token agent prompt compresses to the 24,340 tokens actually sent to the model, and the FATAL line at item 67 survives byte for byte." width="880"><a href="https://trendshift.io/repositories/20881" target="_blank"><img src="https://trendshift.io/api/badge/repositories/20881" alt="headroomlabs-ai/headroom | Trendshift — #1 Repository Of The Day" width="250" height="55"/></a>@@ -11,21 +11,21 @@<a href="https://www.npmjs.com/package/headroom-ai"><img src="https://img.shields.io/npm/v/headroom-ai.svg?color=00F0B5&labelColor=0C1118&label=npm" alt="npm"></a><a href="https://huggingface.co/chopratejas/kompress-v2-base"><img src="https://img.shields.io/badge/model-kompress--v2--base-65D8FF?labelColor=0C1118" alt="Model"></a><a href="https://docs.headroomlabs.ai/docs"><img src="https://img.shields.io/badge/docs-online-00F0B5?labelColor=0C1118" alt="Docs"></a>- <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-98A4B3?labelColor=0C1118" alt="License"></a>+ <a href="https://github.com/headroomlabs-ai/headroom/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-98A4B3?labelColor=0C1118" alt="License"></a></p><p><b><a href="https://docs.headroomlabs.ai/docs/quickstart">Quickstart</a></b> ·<b><a href="#headroom-for-teams">Headroom for Teams</a></b> ·<a href="#get-started-60-seconds">Install</a> ·- <a href="#proof">Proof</a> ·+ <a href="#proof-measured-token-savings">Proof</a> ·<a href="#agent-compatibility">Agents</a> ·<a href="https://docs.headroomlabs.ai/docs">Docs</a> ·<a href="https://discord.gg/yRmaUNpsPJ">Discord</a> ·- <a href="llms.txt">llms.txt</a>+ <a href="https://github.com/headroomlabs-ai/headroom/blob/main/llms.txt">llms.txt</a></p>-<sub><b>AI agents / LLMs:</b> read <a href="llms.txt"><code>/llms.txt</code></a> here, or fetch+<sub><b>AI agents / LLMs:</b> read <a href="https://github.com/headroomlabs-ai/headroom/blob/main/llms.txt"><code>/llms.txt</code></a> here, or fetch<a href="https://docs.headroomlabs.ai/llms.txt">the live index</a> ·<a href="https://docs.headroomlabs.ai/llms-full.txt">full docs blob</a>.</sub>@@ -33,17 +33,53 @@<!-- mcp-name: io.github.headroomlabs-ai/headroom -->-Headroom compresses everything your AI agent reads — tool outputs, logs, RAG-chunks, files, and conversation history — before it reaches the LLM. Same-answers, fraction of the tokens. Compression runs on your machine; no prompt or-file content is sent anywhere to be compressed.+**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](#proof-measured-token-savings)). 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](https://docs.headroomlabs.ai/docs/fastapi) ·+[API reference](https://docs.headroomlabs.ai/docs/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](https://docs.headroomlabs.ai/docs/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](#agent-compatibility) ·+[Proxy](https://docs.headroomlabs.ai/docs/proxy)<p align="center">- <a href="https://headroomlabs.ai"><img src=".github/assets/enterprise-perk.svg" alt="Headroom Enterprise for teams. Talk to us: [email protected]." width="880"></a>+ <a href="https://headroomlabs.ai"><img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/.github/assets/enterprise-perk.svg" alt="Headroom Enterprise for teams. Talk to us: [email protected]." width="880"></a></p><div align="center">- <img src="HeadroomDemo-Fast.gif" alt="Headroom compressing a 10,144 token log dump to 1,260 tokens while preserving the FATAL line" width="820">+ <img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/HeadroomDemo-Fast.gif" alt="Headroom compressing a 10,144 token log dump to 1,260 tokens while preserving the FATAL line" width="820"><br><sub>10,144 → 1,260 tokens. The same <code>FATAL</code> found.</sub></div>@@ -109,7 +145,7 @@ headroom perfheadroom dashboard # live savings (proxy must be running)```-Inline, in Python:+### Reduce input tokens in your own app```pythonfrom headroom import compress@@ -141,7 +177,7 @@ The `headroom` CLI ships only in the PyPI package. The npm `headroom-ai` packageis the TypeScript SDK — a library you import(`import { compress } from 'headroom-ai'`) — and provides no `headroom` command.-## Proof+## Proof: measured token savingsFour scenarios built from real MCP server output formats, measured with theprovider tokenizer and the shipped `compress()`. Seeded and offline, so you get@@ -260,12 +296,12 @@ Saved** card then reads `measured` rather than `estimated`, with the band.| Kimi CLI | ✅ | OAuth bearer forwarded — log in once || ZCode | ✅ | starts the proxy and prints base URLs for ZCode settings |-[^third-party-upstream]: `headroom wrap` routes OpenAI-compatible traffic to the default upstream (`https://api.openai.com/v1`). For a third-party OpenAI-compatible provider (DeepSeek, Together, OpenRouter, a self-hosted gateway), pass `--openai-api-url https://api.deepseek.com/v1` — or set `OPENAI_TARGET_API_URL` before wrapping — otherwise your provider key is sent to OpenAI and rejected with `401 Incorrect API key provided`. See [OpenCode + DeepSeek](docs/content/docs/opencode-deepseek.mdx).+[^third-party-upstream]: `headroom wrap` routes OpenAI-compatible traffic to the default upstream (`https://api.openai.com/v1`). For a third-party OpenAI-compatible provider (DeepSeek, Together, OpenRouter, a self-hosted gateway), pass `--openai-api-url https://api.deepseek.com/v1` — or set `OPENAI_TARGET_API_URL` before wrapping — otherwise your provider key is sent to OpenAI and rejected with `401 Incorrect API key provided`. See [OpenCode + DeepSeek](https://docs.headroomlabs.ai/docs/opencode-deepseek).Any OpenAI-compatible client works through `headroom proxy`. MCP-native clients:`headroom mcp install`. Undo durable wrapping with `headroom unwrap <tool>`(`claude`, `copilot`, `codex`, `grok`, `kimi`, `omp`, `opencode`, `openclaw`,-`zcode`). Registry authors should use the canonical [`server.json`](server.json)+`zcode`). Registry authors should use the canonical [`server.json`](https://github.com/headroomlabs-ai/headroom/blob/main/server.json)rather than reconstructing the `headroom mcp serve` contract from prose.For Anthropic `/v1/messages`, `--mode cache` skips automatic `--memory` context injection so the provider prefix remains stable. OpenAI chat/responses and Gemini append memory to the live-zone tail. Use `--mode token` when you need automatic memory context on the Anthropic path.@@ -365,18 +401,23 @@ session or the resulting context window.## When to use · when to skip-**Good fit if you** run coding agents daily and want savings without touching-your code, work across several agents and want one shared memory, or need-compression that is reversible — originals stay retrievable through CCR for the-configured TTL.+**Use the library** (`compress()`) when your own code builds the prompt: an API+that forwards tool results, logs, search hits, database rows or long chat+history to a model. It is a function over the message list, runs in-process with+no key and no network, and works anywhere Python runs, including sandboxes and+serverless functions.-**Skip it if you** only use one provider's native compaction and don't need-cross-agent memory, or work in a sandbox where local processes can't run.+**Use the proxy or `headroom wrap`** when you want savings on a coding agent or+any client you do not control, with no code changes, or when you want one shared+memory across several agents. Either way, compression is reversible: originals+stay retrievable through CCR for the configured TTL.-Headroom pays off on long agent sessions with heavy tool output. Short-conversational exchanges, prose, and already-dense payloads see little or no-reduction, and blocks under `min_input_words` come back byte-identical.-[Limitations](https://docs.headroomlabs.ai/docs/limitations) has the full list.+**Skip it** for short conversational prompts and prose: there is little to+compress, and blocks under the Kompress `min_input_words` floor come back+byte-identical. If your provider's native compaction already covers your traffic+and you do not need reversibility or cross-agent memory, you may not need+Headroom either. [Limitations](https://docs.headroomlabs.ai/docs/limitations)+has the full list.<details><summary><b>Integrations — drop Headroom into any stack</b></summary>@@ -611,7 +652,7 @@ The Rust core's downloads use rustls with Mozilla's roots and are unaffected by## headroom learn<div align="center">- <img src="headroom_learn.gif" alt="headroom learn mining failed sessions and writing corrections" width="720">+ <img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/headroom_learn.gif" alt="headroom learn mining failed sessions and writing corrections" width="720"></div>`headroom learn` mines failed sessions and writes corrections to@@ -686,7 +727,7 @@ uv sync --extra dev && uv run pytest```Devcontainers in `.devcontainer/` (default, plus `memory-stack` with Qdrant and-Neo4j). See [CONTRIBUTING.md](CONTRIBUTING.md).+Neo4j). See [CONTRIBUTING.md](https://github.com/headroomlabs-ai/headroom/blob/main/CONTRIBUTING.md).## Community@@ -696,4 +737,4 @@ Neo4j). See [CONTRIBUTING.md](CONTRIBUTING.md).## License-Apache 2.0 — see [LICENSE](LICENSE).+Apache 2.0 — see [LICENSE](https://github.com/headroomlabs-ai/headroom/blob/main/LICENSE).