chopratejas/headroom — Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60-95% fewer tokens, same answers. Library, proxy, MCP server.
Alternatives
Same topic — health-ranked peers. Open the matrix or jump to curves only.
Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens.
Live: 10,144 → 1,260 tokens — same FATAL found.
What it does
Library — compress(messages) in Python or TypeScript, inline in any app
Proxy — headroom proxy --port 8787, zero code changes, any language
Agent wrap — headroom wrap claude|codex|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe in one command; undo with headroom unwrap <tool>
MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client
Cross-agent memory — shared store across Claude, Codex, Gemini, auto-dedup
headroom learn — mines failed sessions, writes corrections to CLAUDE.local.md (default, gitignored) or CLAUDE.md / AGENTS.md / GEMINI.md
Output token reduction — trims what the model writes back (not just what you send): drops ceremony/restated code and skips deep "thinking" on routine steps. See Output token reduction.
Reversible (CCR) — originals are cached for retrieval on demand
# 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 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
# 3 — Verify setup and see the savings
headroom doctor # health check — confirms routing is working
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+.
Codex / global install
If Codex or another MCP client cannot inherit a shell PATH reliably, install Headroom as a persistent uv tool and point the client at the absolute binary path:
Output token reduction (cut what the model writes back)
Everything above shrinks the prompt you send. But you also pay for every
token the model writes back — and on Opus-class models output costs 5× input.
A lot of that output is waste: "Great, let me…" preambles, re-printing code you
just showed it, and deep "thinking" on routine steps like reading a file.
Headroom can trim that too, from the proxy, without you changing any code:
Verbosity steering — appends a short "be terse, don't restate context"
note to the end of the system prompt (so your prompt cache still hits).
Effort routing — when a turn is just the model resuming after a tool result
(a file read, a passing test), it dials the model's thinking effort down. New
questions and errors keep full effort.
Turn it on:
export HEADROOM_OUTPUT_SHAPER=1 # off by default
headroom proxy --port 8787
Already running a proxy? These switches are read live on every request,
so a proxy that headroom wrapreused (rather than started) would not see
a value you export afterwards — its environment was snapshotted at launch.
headroom wrap now hot-syncs your current settings to the running proxy via a
loopback POST /admin/runtime-env, so they take effect immediately with no
restart (no cold start, no dropped requests, no lost caches). Set them before
you wrap. On a shared proxy these overrides are global — the last explicit
setting wins.
Learn the right terseness for you. People don't say how terse they want
answers — they show it (they interrupt long replies, or move on before they
could have read them). headroom learn --verbosity reads your past sessions and
picks the level automatically:
headroom learn --verbosity # preview what it found (dry run)
headroom learn --verbosity --apply # save it; the proxy uses it from now on
See how many output tokens you saved. Output savings are counterfactual —
we never see what the model would have written — so Headroom reports an honest
estimate with a confidence range, never a made-up number:
Want a measured number instead of an estimate? Leave 10% of conversations
unshaped as a control group: export HEADROOM_OUTPUT_HOLDOUT=0.1. The dashboard
shows an Output Tokens Saved card next to input compression, labelled
measured or estimated with the confidence band.
This lets Headroom intercept OpenAI-compatible Copilot CLI requests and apply the same proxy compression pipeline before forwarding to GitHub Copilot's hosted API. The wrapper exchanges Headroom's reusable GitHub OAuth token for Copilot's short-lived API token and prints the upstream endpoint as COPILOT_PROVIDER_API_URL=... during launch.
headroom copilot-auth login stores a Headroom-specific Copilot OAuth token.
This avoids relying on generic GitHub or Copilot CLI tokens that can read
Copilot account metadata but may still be rejected by Copilot's token-exchange
endpoint.
For GitHub Enterprise Server or custom-domain Copilot deployments, set the
deployment domain before launching:
For GitHub.com Enterprise Cloud URLs such as
github.com/enterprises/your-enterprise, do not set an enterprise-domain
override. Headroom uses GitHub's normal token-exchange endpoint and the Copilot
API endpoint advertised for the signed-in account.
Platform support note: macOS auth reuse via Copilot CLI Keychain storage has been smoke-tested. Windows Credential Manager, Linux Secret Service / secret-tool, and Docker/CI token-injection paths are implemented or planned as auth-discovery paths, but still need real OS validation before they should be considered fully vetted. For Docker and CI, prefer passing an explicit GITHUB_COPILOT_TOKEN or GITHUB_COPILOT_GITHUB_TOKEN rather than relying on host keychain access.
When to use · When to skip
Great fit if you…
run AI coding agents daily and want savings without changing your code
work across multiple agents and want shared memory
need reversible compression — originals are retrievable via CCR within the configured TTL
Skip it if you…
only use a single provider's native compaction and don't need cross-agent memory
work in a sandboxed environment where local processes can't run
Kompress-v2-base — our HuggingFace model, trained on agentic traces.
Image compression — 40–90% reduction via trained ML router.
CacheAligner — stabilizes prefixes so Anthropic/OpenAI KV caches actually hit.
Live-zone compression — compresses only new bytes (fresh tool output, latest turn); frozen prefix stays byte-identical so provider cache is not busted. History is never dropped.
CCR — reversible compression; LLM retrieves originals on demand.
Transforms do the work: CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base (live-zone only; IntelligentContext and RollingWindow were retired in PR-B1).
Pipeline extensions observe or customize lifecycle stages via on_pipeline_event(...).
Compression hooks sit alongside the canonical lifecycle as an additional extension seam.
Proxy extensions remain the server/app integration seam for ASGI middleware, routes, and startup policy.
Provider and tool-specific behavior lives under headroom/providers/ so core orchestration stays focused on lifecycle, sequencing, and policy.
Provider runtime slices: headroom/providers/claude, gemini, plus shared backend/runtime dispatch in headroom/providers/registry.py
Core files stay orchestration-first: wrap.py, client.py, cli/proxy.py, and proxy/server.py delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch.
Headroom for teams
Headroom OSS is built for individual developers: run headroom proxy or headroom wrap on your laptop and start cutting tokens in minutes — free, local-first, your data never leaves your machine.
Running it across a whole engineering org is a different job: a shared, always-on deployment; centralized config and version rollout; org-wide savings dashboards; SSO and access controls; air-gapped / VPC installs; and someone to call when it matters. That's what we help companies with — self-hosted with support, or fully managed.
If your team is spending real money on LLM tokens — Claude Code, Codex, Cursor, or agents running in CI — and you want those savings across everyone, not just one laptop:
→ Email hello@headroomlabs.ai with your stack and rough monthly LLM spend, and we'll help you roll Headroom out across your organization.
Everything in this repo stays open source (Apache 2.0). The managed offering is simply for teams that would rather have it deployed, supported, and scaled for them.
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
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). Requires Python 3.10+.
Note: [all] covers the core stack but excludes framework adapters. Install them separately: pip install "headroom-ai[langchain]" (also [agno], [strands], [anyllm], [bedrock]).
Using pipx? Choose a supported interpreter explicitly:
Pick 3.13 if you want dollar savings. The dashboard's Proxy $ Saved tile prices compression with LiteLLM, and LiteLLM can't be installed on Python 3.14+. On 3.14 token savings still track, but the dollar figure stays $0.00. If you already installed on 3.14, switch with pipx reinstall headroom-ai --python python3.13 and restart the proxy.
CPU requirement (x86/x86_64): the ONNX-backed features — Magika content
detection and embedding relevance — use a precompiled ONNX Runtime that needs
AVX2. On x86 hosts without AVX2 (some Docker/QEMU setups and older cloud
VMs) Headroom automatically falls back to its non-ONNX paths (BM25 relevance,
heuristic detection) rather than crashing. arm64/Apple Silicon needs no AVX2.
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
headroom update figures out how Headroom was installed (pip/venv, pip --user,
pipx, uv tool) and runs the matching upgrade across macOS, Linux, and Windows.
For git checkouts, editable installs, Docker images, and externally-managed
system Pythons (PEP 668) it prints the correct manual step instead of guessing.
The proxy also shows a one-line "update available" notice on startup. It checks
PyPI at most once a day, in the background, and never blocks. Opt out with
HEADROOM_UPDATE_CHECK=off (also skipped in --stateless mode and CI).
Corporate / SSL-inspection environments
If pip install "headroom-ai[all]" fails with CERTIFICATE_VERIFY_FAILED
(unable to get local issuer certificate), your network uses SSL inspection — a MITM
proxy presenting a company-issued CA. The build backend (maturin) downloads rustup over a
connection your TLS stack doesn't trust. Install Rust first so the build doesn't fetch it:
# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# Windows
winget install Rustlang.Rustup && rustup default stable
Restart your shell, then pip install "headroom-ai[all]". A prebuilt wheel avoids the Rust
build entirely where available: pip install --only-binary headroom-ai headroom-ai. Prebuilt
wheels are published for Windows (win_amd64), Linux (x86_64 / aarch64), and macOS
(Apple Silicon and Intel), so installs on those platforms never need a local Rust toolchain — the
Rust-first dance above is only for the platform-independent sdist fallback when no wheel matches.
Two runtime assets are fetched over TLS; if they are blocked, trust your corporate CA via
REQUESTS_CA_BUNDLE / SSL_CERT_FILE / CURL_CA_BUNDLE:
cdn.pyke.io — the ONNX Runtime for the Rust core. Alternatively pre-provide it with
ORT_STRATEGY=system and ORT_LIB_LOCATION=/path/to/onnxruntime.
huggingface.co — the kompress-base compression model. Pre-download it and run with
HF_HUB_OFFLINE=1, or set HF_ENDPOINT to a trusted mirror.
Running with compression disabled (pure gateway) requires neither asset.
"Basic Constraints of CA cert not marked critical" (Python 3.13+ strict mode)
A different failure from the one above. If TLS fails with:
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
Basic Constraints of CA cert not marked critical
then the corporate CA is found and trusted — adding it to a CA bundle changes nothing.
Python 3.13 + OpenSSL 3.x enable VERIFY_X509_STRICT by default, which enforces RFC 5280
§4.2.1.9: a CA cert's basicConstraints must be marked critical. Inspection roots like
Zscaler set CA:TRUE without the critical bit, so the chain is rejected.
Set HEADROOM_TLS_STRICT=0 to clear only the strict flag from every TLS context
Headroom controls — the proxy's httpx upstream client and the urllib3/huggingface_hub
path used for model downloads. Chain validation, signature, expiry, and hostname checks all
stay on; this is strictly narrower than disabling verification.
HEADROOM_TLS_STRICT=0 headroom proxy --port 8787
The Rust core's ONNX download (cdn.pyke.io) uses a separate TLS stack (rustls / OS trust
store), unaffected by HEADROOM_TLS_STRICT. On Windows the corporate root must be in the
machine certificate store (browsers already trust it there); or pre-provision ONNX
Runtime with ORT_STRATEGY=system + ORT_LIB_LOCATION=/path/to/onnxruntime to skip the
download entirely.
headroom learn
headroom learn — mines failed sessions, writes corrections to CLAUDE.local.md (default, gitignored; use --target CLAUDE.md for the shared team file) / AGENTS.md / GEMINI.md.
Attribution. Headroom ships with the excellent RTK binary for shell-output rewriting — git show --short, scoped ls, summarized installers. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use lean-ctx as the selected CLI context tool; set HEADROOM_CONTEXT_TOOL=lean-ctx before running headroom wrap ....
Contributing
git clone https://github.com/chopratejas/headroom.git && cd headroom
uv sync --extra dev && uv run pytest
Devcontainers in .devcontainer/ (default + memory-stack with Qdrant & Neo4j). See CONTRIBUTING.md.
