headroomlabs-ai/headroom

What it claims

Headroom compresses everything an agent reads (tool outputs, logs, RAG chunks, files, history) locally before it hits the LLM, and separately trims what the model writes back. The page puts numbers on both: repetitive JSON arrays and log lines clear 90%+ compression, while prose and already-dense output "compress very little"; output-side reduction is reported as 31.7% (95% CI 27.7–35.7%), labeled [estimated]. Compression latency is 0.21 ms p50 on a 10K-token JSON result, 1.4 ms at 100K. Accuracy check: TruthfulQA at N=100 shows "no detectable difference" (±0.03 delta inside the CI, not an improvement).

How it works

Per-request pipeline: CacheAligner → ContentRouter → SmartCrusher (JSON) / CodeCompressor (AST, for Python/JS/TS/Go/Rust/Java/C/C++/C#/PHP) / Kompress-v2-base (prose), applied to the live zone only. CacheAligner flags volatile content that would bust a provider KV-cache prefix and never rewrites prompts; only new bytes are compressed so the frozen prefix stays byte-identical and history is never dropped. CCR caches originals locally for retrieval on demand.

Output reduction (proxy-side, off by default) has two mechanisms: verbosity steering appends a "be terse" note to the end of the system prompt to preserve prompt cache; effort routing dials thinking effort down only when a turn is the model resuming after a tool result, keeping full effort for new questions and errors. Both work on Anthropic /v1/messages and OpenAI /v1/chat/completions and /v1/responses.

How to use it

uv tool install --python 3.13 "headroom-ai[all]"   # CLI, isolated env
pip install "headroom-ai[all]"                      # Python + CLI
npm install headroom-ai                             # TS SDK only — NO CLI
docker pull ghcr.io/headroomlabs-ai/headroom:latest

Modes: headroom wrap claude (also installs Serena at user scope, starts a local proxy), headroom proxy --port 8787, or inline from headroom import compress. Enable output shaping with export HEADROOM_OUTPUT_SHAPER=1. For a measured output number, hold out a control: export HEADROOM_OUTPUT_HOLDOUT=0.1. [all] excludes framework adapters — install [langchain], [agno], [strands], etc. separately. Requires Python 3.10+.

Limits

• npm package ships no headroom command — TS library only; CLI is PyPI-only.
• Anonymous telemetry beacon is ON by default (ratios, counters, provider/model/OS IDs — never prompts or code). Opt out with HEADROOM_BEACON=off, DO_NOT_TRACK=1, or --offline.
• Native wheels cover macOS Apple Silicon and Linux only; Intel macOS needs the Docker install or a system ONNX Runtime. ONNX features (Magika detection, embedding relevance) need AVX2 on x86, falling back to BM25/heuristics otherwise.
• Corporate SSL inspection breaks the maturin/rustup build and two TLS asset fetches (cdn.pyke.io, huggingface.co); the page documents HEADROOM_TLS_STRICT=0 and CA-bundle workarounds.
• Little or no gain on short exchanges, prose, dense payloads; blocks under min_input_words return byte-identical. The org-scale deployment (SSO, dashboards, air-gapped) is a paid managed offering, though the repo stays Apache 2.0.