Install and CLI
Commands and package names are quoted from the Headroom README. The CLI surface changes between releases — run headroom --help and check the installation guide for the current set.
1. Install​
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
The headroom command comes only from the PyPI package. The npm headroom-ai is the TypeScript SDK — a library you import (import { compress } from 'headroom-ai'), not a CLI. If you installed via npm and headroom is "command not found", that is expected.
Requires Python 3.10+.
2. Optional extras​
[all] covers the core stack but excludes framework adapters. Install those separately, e.g. pip install "headroom-ai[langchain]" (also [agno], [strands], [anyllm], [bedrock]).
Granular extras: [proxy], [mcp], [ml] (Kompress-v2-base), [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).
pipx and the Python version trap​
pipx install --python python3.13 "headroom-ai[all]"
Per the README, pick Python 3.13 if you want the dollar-savings figure. The dashboard prices compression via LiteLLM, and LiteLLM cannot install on Python 3.14+. On 3.14 token savings still track, but the dollar figure stays $0.00. To switch: pipx reinstall headroom-ai --python python3.13 and restart the proxy.
3. First run (60 seconds)​
headroom wrap claude # wrap a coding agent
headroom proxy --port 8787 # drop-in proxy, zero code changes
headroom doctor # health check — confirms routing works
headroom perf # show performance / savings
headroom dashboard # live savings dashboard (proxy must be running)
4. CLI reference​
| Command | What it does |
|---|---|
headroom proxy --port 8787 | Start the local, drop-in compression proxy |
headroom wrap <tool> | Route a supported agent through Headroom |
headroom unwrap <tool> | Undo durable wrapping (claude, copilot, codex, opencode, openclaw) |
headroom doctor | Health check — confirms compression routing is working |
headroom perf / headroom savings | Report performance and token/cost savings |
headroom dashboard | Live savings dashboard (requires a running proxy) |
headroom learn | Mine failed sessions, write corrections to memory files |
headroom learn --verbosity | Learn your preferred output terseness (see proxy page) |
headroom output-savings | Report estimated output-token savings with a confidence range |
headroom mcp install | Install Headroom as an MCP server |
headroom init / headroom install apply | Set up a persistent install |
headroom update [--check] [--pre] | Upgrade in place; detects pip/pipx/uv |
python -m headroom.evals suite --tier 1 | Reproduce the benchmark suite |
5. Updating​
headroom update # detects pip / pipx / uv tool and upgrades in place
headroom update --check # report the latest release without upgrading
headroom update --pre # include pre-releases
For git checkouts, editable installs, Docker images, and externally-managed system Pythons (PEP 668), headroom update prints the correct manual step instead of guessing. The proxy also shows a once-a-day, non-blocking "update available" notice on startup; opt out with HEADROOM_UPDATE_CHECK=off.
6. Corporate / SSL-inspection networks​
If pip install "headroom-ai[all]" fails with CERTIFICATE_VERIFY_FAILED, your network likely uses SSL inspection. Two situations, two fixes — both documented in the README and summarized on the Troubleshooting page:
- The Rust build backend fetches
rustupover an untrusted connection → install Rust first, or use a prebuilt wheel:pip install --only-binary headroom-ai headroom-ai. - Python 3.13 strict TLS rejects a non-critical corporate CA → set
HEADROOM_TLS_STRICT=0(narrows only the strict flag; all other verification stays on).