Skip to content

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.

Install using uv tool globally (#1829)

Dustin Burke4d433592deaa
diff --git a/README.md b/README.md
index 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 env
pip install "headroom-ai[all]" # Python — ships the `headroom` CLI
npm 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 agent
headroom proxy --port 8787 # drop-in proxy, zero code changes
# or: from headroom import compress # inline library
@@ -101,6 +102,8 @@ headroom perf
headroom 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+**.