Headroom: open-source LLM prompt compressor cuts tokens 20-95% locally

Headroom is a locally-run compression layer for AI agents and LLM applications. It intercepts prompts, tool outputs, logs, and retrieval chunks, then routes them through content-specific compressors—SmartCrusher for JSON, CodeCompressor for source code, and Kompress-v2-base for text—before forwarding to the LLM provider. The project offers a Python/TypeScript library, a zero-code-change proxy, one-command agent wrappers for Claude, Cursor, Codex and others, and an MCP server. Compression runs entirely on the user's machine with no data sent externally for processing.

How Headroom compresses without changing answers

• ContentRouter detects payload type and selects the appropriate compressor: SmartCrusher for JSON, CodeCompressor (AST-based) for source code, Kompress-v2-base (Hugging Face model) for prose
• CacheAligner flags volatile content that would break provider KV-cache prefix matching, without rewriting prompts
• CCR (Compress-Cache-Retrieve) stores originals locally; the model can call headroom_retrieve when full text is needed
• Cross-agent memory provides deduplicated shared storage across Claude, Codex, Gemini, and Grok sessions
• Output token reduction also trims what the model writes back, not just inbound traffic
• Latency cost: 0.21 ms p50 at 10K tokens, 1.4 ms at 100K tokens on benchmark hardware

Why it matters

Headroom addresses a growing cost bottleneck for AI agent deployments where tool outputs and RAG results can balloon context windows. By running compression locally and offering MCP server integration, it fits into existing agent stacks without vendor lock-in. The cross-agent memory and headroom learn features suggest a move toward persistent, self-improving agent infrastructure.