Headroom FAQ

Headroom is a context compression layer for AI agents. It compresses everything your AI agent reads—including tool outputs, logs, RAG chunks, files, and conversation history—before it reaches the LLM. This means you get the same answers but with a fraction of the tokens, leading to significant cost savings and faster response times.

Headroom runs locally on your machine, ensuring that no prompt or file content is sent anywhere to be compressed. It works as a library, a proxy, or by wrapping your existing AI agents.

Headroom uses a multi-stage pipeline to intelligently compress context:

1. ContentRouter: Detects the content type (JSON, code, prose, etc.) and selects the best compressor.
2. SmartCrusher / CodeCompressor / Kompress-v2-base: Specialized compressors for different content types.
3. CacheAligner: Flags volatile content that would disrupt a provider's KV-cache, ensuring prompt caching remains effective.
4. CCR (Cacheable Compressed Retrieval): Stores originals locally and allows the model to retrieve them on demand using tools like headroom_retrieve.

This process is reversible, meaning the original content is always available if the model needs it.

Savings depend on the type of content being compressed. Here are some real-world examples:

Highly repetitive content, like JSON arrays and logs, can see reductions of 90% or more.

Yes, the compression is designed to be highly accurate. We've run benchmarks on standard datasets to ensure there's no detectable loss in quality:

At our scale, the delta for TruthfulQA falls within the confidence interval, showing no detectable difference. The SQuAD v2 and BFCL benchmarks also show 97% accuracy at significant compression levels.

Headroom offers extensive compatibility with major AI coding agents and tools. You can use it as a library, a proxy, or by wrapping specific agents.

Full `headroom wrap` support:

• Claude Code
• Codex
• Grok CLI
• Aider
• Copilot CLI
• OpenClaw
• OpenCode
• Cline
• Continue
• Goose
• OpenHands
• Mistral Vibe
• Oh My Pi
• Kimi CLI
• ZCode

Proxy support: Any OpenAI-compatible client works through the `headroom proxy` command. This includes VS Code Copilot and other third-party tools.

Manual setup: Cursor requires a manual setup, but Headroom can start the proxy and print the necessary configuration URLs.

For a complete list and detailed setup instructions for each agent, please refer to our Agent Compatibility documentation.

Getting started with Headroom is designed to be quick and easy. You can be up and running in under 60 seconds.

You can also use Headroom as a library directly in your Python or TypeScript applications. See our Quickstart guide for more details.

Headroom OSS is designed for individual developers on a single machine. Headroom Enterprise is built for teams and organizations.

Special Offer: Companies that sign a 12-month Enterprise plan get their first 3 months free. Claim 3 months free →

Headroom requires **Python 3.10+** for its core functionality. The installation method varies:

• macOS / Linux: Native wheels are available for Apple Silicon and x86_64. On Intel macOS, a Docker install is recommended until native wheels are available.
• Windows: Native wheels are available for win_amd64.
• ARM64: Supported on Linux and Apple Silicon. No AVX2 requirement.

CPU Requirement (x86/x86_64): The ONNX-backed features (Magika content detection and embedding relevance) require AVX2. On hosts without AVX2, Headroom gracefully falls back to non-ONNX paths (BM25 relevance, heuristic detection) instead of crashing.

For corporate networks with SSL inspection, specific environment variables may be needed to trust custom CAs. See our Corporate Networks guide for details.

Headroom includes an anonymous telemetry beacon that is **on by default**. This beacon reports high-level usage data to help the development team understand how the tool is used in the wild. It never sends prompts, completions, code, or file paths.

The data collected includes:

• Compression ratios and token savings
• Request counters
• Provider and model IDs
• Operating system and architecture

This telemetry is crucial for identifying when a release might regress performance across real-world workloads, allowing for faster improvements.

You can disable telemetry by setting any of these environment variables: HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off, DO_NOT_TRACK=1, or HEADROOM_OFFLINE=1.

Headroom is licensed under the Apache License 2.0. This permissive license allows you to use, modify, and distribute the software freely, even for commercial purposes. The only requirement is to include the original license and copyright notice in any copies of the software you distribute.

All code in this repository is open source. The Kompress-v2-base model is also available on Hugging Face and is subject to its own license terms.