Headroom is a context compression tool designed to reduce token consumption for AI agents and language models by compressing tool outputs, logs, files, and RAG chunks before they reach the LLM. The repository demonstrates real-world token savings of 60-95% across various workloads while maintaining answer accuracy, making it particularly valuable for cost-sensitive AI applications where context window management is critical.
The project is implemented primarily in Python and offers three deployment modes to accommodate different use cases. As a library, developers can call compress functions directly in Python or TypeScript applications. As a proxy server, it requires zero code changes and works with any language or framework by intercepting requests. As an MCP server, it integrates with any MCP-compatible client through dedicated compression, retrieval, and statistics endpoints. The repository also provides agent wrapping functionality that automatically configures popular AI tools including Claude Code, Cursor, Aider, Cline, Continue, and others with a single command.
The compression architecture relies on several specialized components. ContentRouter automatically detects content types and selects appropriate compressors. SmartCrusher, CodeCompressor, and a custom Kompress-v2-base model handle compression of JSON, abstract syntax trees, and prose respectively. CacheAligner stabilizes prefixes to maximize provider KV cache hits. The reversible compression system (CCR) caches original content locally, allowing the LLM to retrieve uncompressed versions on demand through MCP calls if needed.
Accuracy benchmarks demonstrate that compression preserves model performance, with GSM8K maintaining 0.870 accuracy, TruthfulQA improving to 0.560, and SQuAD v2 achieving 97% accuracy with 19% compression.
Beyond input compression, Headroom addresses output token reduction through verbosity steering and effort routing. Verbosity steering appends terseness guidance to system prompts while preserving prompt cache hits. Effort routing reduces model thinking on routine tasks like file reads while maintaining full effort for novel questions and errors. The headroom learn command mines failed sessions to automatically calibrate verbosity levels based on user behavior patterns.
Installation is available via PyPI for Python 3.10 and above, with optional extras for proxy, MCP, machine learning, code analysis, memory, vector operations, relevance scoring, image processing, and framework integrations. The project is licensed under Apache 2.0 and maintains comprehensive documentation at headroom-docs.vercel.app.
