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.

Address PR feedback: Move troubleshooting, refine rust docs, and update install options

Divyanshu Singh67f005e434f8
diff --git a/README.md b/README.md
index 74838f3e2..537df049e 100644
--- a/README.md
+++ b/README.md
@@ -280,62 +280,4 @@ Devcontainers in `.devcontainer/` (default + `memory-stack` with Qdrant & Neo4j)
## License
-Apache 2.0 — see [LICENSE](LICENSE).
----
-
-## Troubleshooting
-
-These are common issues faced during initial setup and how to resolve them.
-
-### Python version error
-
-This project requires **Python 3.10+**.
-
-Check your version:
-
-```bash
-python3 --version
-```
-
-If needed (Mac with Homebrew):
-
-```bash
-brew install [email protected]
-```
-
----
-
-### Editable install fails (`pip install -e`)
-
-Upgrade pip to the latest version:
-
-```bash
-python3 -m pip install --upgrade pip
-```
----
-
-### Missing `cargo` (Rust error)
-
-Some tests require Rust tooling.
-
-Install Rust using the official installer:
-
-```bash
-curl https://sh.rustup.rs -sSf | sh
-```
-
-Or visit the official site:
-https://rust-lang.org/tools/install/
-
----
-
-### npm vs Python confusion
-
-* This repository is primarily a **Python project**
-* `npm install headroom-ai` is only for using it in JavaScript/TypeScript apps, not for development
-
-To contribute to this repository, use:
-
-```bash
-pip install ".[dev]"
-```
\ No newline at end of file
+Apache 2.0 — see [LICENSE](LICENSE).
\ No newline at end of file
diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdx
index 08b82e260..e13605720 100644
--- a/docs/content/docs/installation.mdx
+++ b/docs/content/docs/installation.mdx
@@ -3,6 +3,14 @@ title: Installation
description: Install Headroom via pip, npm, or Docker. Includes all Python extras, TypeScript setup, Docker image tags, and environment variables.
---
+---
+
+## Install options
+
+**pip** - you're writing Python, or you need the CLI (`headroom proxy`, `wrap`, `mcp`, `learn`, `perf`), regardless of what language your app is in.
+
+**npm** - you're writing TypeScript/Node and want inline `compress()`, SDK wrapping (`withHeadroom`), or Vercel AI SDK middleware.
+
## Python
Headroom requires **Python 3.10+** and is published as `headroom-ai` on PyPI.
@@ -184,6 +192,40 @@ These variables configure Headroom at runtime. Set them in your shell, `.env` fi
| `HEADROOM_BASE_URL` | `http://localhost:8787` | Proxy URL for the TypeScript SDK |
| `HEADROOM_API_KEY` | _(none)_ | API key if the proxy requires auth |
+## Troubleshooting
+
+These are common issues faced during initial setup and how to resolve them.
+
+### Python version error
+
+This project requires **Python 3.10+**.
+
+Check your version:
+
+```bash
+python3 --version
+```
+
+If needed (Mac with Homebrew):
+
+```bash
+brew install [email protected]
+```
+
+### Editable install fails (`pip install -e`)
+
+Upgrade pip to the latest version:
+
+```bash
+python3 -m pip install --upgrade pip
+```
+
+### Missing `cargo` (Rust error)
+
+Some tests require Rust tooling.
+
+The recommended way to install rust is using `rustup`. You can find the official installation instructions [here](https://rust-lang.org/tools/install/).
+
## Next steps
<Cards>