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
README: proxy as the hero quickstart, compress() for Python, integration table for existing proxies
chopratejasf699375f8f88
diff --git a/README.md b/README.mdindex c8130f857..e80f78332 100644--- a/README.md+++ b/README.md@@ -45,40 +45,47 @@pip install "headroom-ai[all]"```+### Simplest: Proxy (zero code changes)++```bash+headroom proxy --port 8787+```++```bash+# Claude Code — just set the base URL+ANTHROPIC_BASE_URL=http://localhost:8787 claude++# Cursor, Continue, any OpenAI-compatible tool+OPENAI_BASE_URL=http://localhost:8787/v1 cursor+```++Works with any language, any tool, any framework. One env var. **[Proxy docs](docs/proxy.md)**++### Python: One function+```pythonfrom headroom import compress-messages = [- {"role": "user", "content": "What caused the outage?"},- {"role": "tool", "content": huge_log_output, "tool_call_id": "call_1"},-]-result = compress(messages, model="claude-sonnet-4-5-20250929")-# result.messages → same format, 50-90% fewer tokens-# result.tokens_saved → 8,000-# result.compression_ratio → 0.87-response = client.messages.create(model="claude-sonnet-4-5-20250929", messages=result.messages)+print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")```-**Same answer. 87% fewer tokens.**-----+Works with any Python LLM client — Anthropic, OpenAI, LiteLLM, httpx, anything.-## How to Use Headroom+### Already have a proxy or gateway?-Headroom is a compression library, not just a proxy. Use whichever integration fits your stack:+You don't need to replace it. Drop Headroom into your existing stack:-| You have... | Use this | Code |-|-------------|----------|------|-| Any Python app | `compress()` | `result = compress(messages, model="gpt-4o")` |-| LiteLLM | Callback | `litellm.callbacks = [HeadroomCallback()]` |-| Python proxy (FastAPI) | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` |-| Claude Code / Cursor | Proxy | `ANTHROPIC_BASE_URL=http://localhost:8787 claude` |-| Agno agents | Wrap model | `HeadroomAgnoModel(your_model)` |-| LangChain | Wrap model | `HeadroomChatModel(your_llm)` *(experimental)* |+| Your setup | Add Headroom | One-liner |+|------------|-------------|-----------|+| **LiteLLM** | Callback | `litellm.callbacks = [HeadroomCallback()]` |+| **Any Python proxy** | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` |+| **Any Python app** | `compress()` | `result = compress(messages, model="gpt-4o")` |+| **Agno agents** | Wrap model | `HeadroomAgnoModel(your_model)` |+| **LangChain** | Wrap model | `HeadroomChatModel(your_llm)` *(experimental)* |-**Already have a proxy?** You don't need another one. See the **[Integration Guide](docs/integration-guide.md)** for detailed setup with LiteLLM, ASGI middleware, and direct `compress()` usage.+**[Full Integration Guide](docs/integration-guide.md)** — detailed setup for LiteLLM, ASGI middleware, compress(), and every framework.---