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.
Real-world performance metrics from the README show substantial token reduction across diverse workloads: code search reduced from 17,765 to 1,408 tokens (92% savings), SRE incident debugging from 65,694 to 5,118 tokens (92% savings), GitHub issue triage from 54,174 to 14,761 tokens (73% savings), and codebase exploration from 78,502 to 41,254 tokens (47% savings). 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.
GitGenius tracking shows the repository has grown from 56,510 to 56,513 stargazers since July 2026. The project maintains active issue and pull request management with a median response latency of 0.0 hours and mean latency of 23.3 hours across 515 tracked items. The most active contributor is chopratejas with 344 events, followed by JerrettDavis with 130 events and damnthonyy with 46 events. Bug reports comprise the most active issue label with 152 items, followed by enhancement requests with 88 items. The project shares contributors with related repositories including chopratejas/headroom, diegosouzapw/omniroute, and anthropics/claude-code, indicating active collaboration within the AI agent ecosystem.
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.
