Headroom Compresses Large Language Model Inputs by Up to Ninety Five Percent
Headroom is an open-source tool designed to compress LLM prompt inputs by 60% to 95% without sacrificing retrieval accuracy. It works by semantically analyzing and pruning redundant tokens before sending them to the API, drastically reducing costs. This tool is ideal for developers building context-heavy applications.
Why it matters
You can integrate Headroom into your LLM pipeline today to slash active token costs and bypass context window limitations.
TL;DR
- 01Achieve 60% to 95% prompt token reduction using semantic compression middleware.
- 02Works out of the box with major LLM APIs by intercepting and optimizing prompt payloads.
- 03Reduces operational latency and API costs for context-heavy applications.
Key facts
- Token Reduction Range
- 60-95%
- Default Proxy Port
- 8787
- Required Python Version
- Python 3.10+
Local Context Compression
Headroom operates locally to reduce LLM prompt tokens by 60% to 95%. It processes logs, files, tool outputs, and RAG chunks before they reach the LLM, lowering API costs while maintaining retrieval accuracy. It includes algorithms like SmartCrusher for JSON, CodeCompressor for AST-aware code compression, and CacheAligner to stabilize prefix matching so provider KV caches actually hit.
Multiple Integration Modes
Developers can run Headroom in multiple ways: as a Python or TypeScript library via from headroom import compress, as a drop-in local proxy on port 8787 with zero code changes, or by wrapping existing CLI agents using headroom wrap claude. It also supports Model Context Protocol (MCP) clients with integrated commands like headroom_compress and headroom_retrieve.
Reversible Architecture & Memory
Through Cached Context Retrieval (CCR), the original uncompressed context is cached locally, allowing the LLM to call headroom_retrieve on demand. Additionally, headroom learn analyzes failed user sessions to write direct corrections to files like CLAUDE.md or AGENTS.md.
Try it in 2 minutes
pip install "headroom-ai[all]" && headroom proxy --port 8787bash
✓ When to use
- When running AI coding agents daily and looking to save on LLM token costs without changing application code.
- When working across multiple agents and requiring a shared context memory store.
- When requiring reversible compression where original uncompressed inputs can be retrieved dynamically.
✕ When NOT to use
- When using only a single provider's native compaction and cross-agent memory is not needed.
- When working in a strictly sandboxed environment where local background processes cannot run.
Sources