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
Install using uv tool globally (#1829)
Dustin Burke4d433592deaa
diff --git a/README.md b/README.mdindex 955babf23..42a438ebe 100644--- a/README.md+++ b/README.md@@ -87,10 +87,11 @@ Headroom compresses everything your AI agent reads — tool outputs, logs, RAG c```bash# 1 — Install+uv tool install "headroom-ai[all]" # Install `headroom` CLI as a global tool in self-contained virtual envpip install "headroom-ai[all]" # Python — ships the `headroom` CLInpm install headroom-ai # TypeScript SDK only — no `headroom` CLI-# 2 — Pick your mode (the `headroom` commands below come from the pip install)+# 2 — Pick your mode (the `headroom` commands below come from the uv or pip install)headroom wrap claude # wrap a coding agentheadroom proxy --port 8787 # drop-in proxy, zero code changes# or: from headroom import compress # inline library@@ -101,6 +102,8 @@ headroom perfheadroom dashboard # live savings dashboard (proxy must be running)```+To use headroom, it is recommended you launch a wrapped agent session each time so that all necessary setup is completed. When wrapping a coding agent, headroom starts a local proxy, sets up an MCP server that provides tools such as rtk and tokensave, and launches a coding agent session configured to proxy requests to headroom.+The `headroom` CLI ships **only** via the PyPI package. The npm `headroom-ai` is the TypeScript SDK — a library you import (`import { compress } from 'headroom-ai'`), not a CLI, so it provides no `headroom` command.Granular extras: `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain, not in `[all]`), `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`, `[pytorch-mps]` (Apple-GPU memory-embedder offload — set `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.10+**.