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.

docs: clarify the headroom CLI is pip-only; npm headroom-ai is the TS SDK (#1585)

Manmit Singhabab3ccbfcae
diff --git a/README.md b/README.md
index 8e26ec8f8..ce7b7655a 100644
--- a/README.md
+++ b/README.md
@@ -87,10 +87,10 @@ Headroom compresses everything your AI agent reads — tool outputs, logs, RAG c
```bash
# 1 — Install
-pip install "headroom-ai[all]" # Python
-npm install headroom-ai # Node / TypeScript
+pip install "headroom-ai[all]" # Python — ships the `headroom` CLI
+npm install headroom-ai # TypeScript SDK only — no `headroom` CLI
-# 2 — Pick your mode
+# 2 — Pick your mode (the `headroom` commands below come from the 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 +101,8 @@ headroom perf
headroom dashboard # live savings dashboard (proxy must be running)
```
+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+**.
## Proof
@@ -319,8 +321,8 @@ Everything in this repo stays open source (Apache 2.0). The managed offering is
## Install
```bash
-pip install "headroom-ai[all]" # Python, everything
-npm install headroom-ai # TypeScript / Node
+pip install "headroom-ai[all]" # Python, everything — includes the `headroom` CLI
+npm install headroom-ai # TypeScript SDK (library only — no `headroom` CLI)
docker pull ghcr.io/chopratejas/headroom:latest
```
diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdx
index b09dd2596..ee3bbae0c 100644
--- a/docs/content/docs/installation.mdx
+++ b/docs/content/docs/installation.mdx
@@ -127,7 +127,7 @@ python -c "import headroom; print(headroom.__version__)"
## TypeScript / Node.js
-The TypeScript SDK is published as `headroom-ai` on npm. It requires **Node.js 18+**.
+The TypeScript SDK is published as `headroom-ai` on npm. It requires **Node.js 18+**. It is a library you import — it does **not** install the `headroom` CLI (`headroom wrap`, `headroom proxy`, etc.), which ships only with the Python package above.
```bash
npm install headroom-ai