Project screenshots
Overview
Headroom intercepts the data flowing from your application or AI agent to an LLM provider and compresses it locally. It uses a content-aware routing system to select the appropriate compressor for different data types, such as JSON, code, or natural prose. Beyond input compression, it includes an output token reduction feature that trims verbose model responses. It also provides reversible compression by caching originals locally, allowing the LLM to retrieve them on demand via an MCP tool.
Key features
- Library, proxy, and MCP server deployment modes
- Content-aware compression for JSON, code, and text
- Reversible compression with local caching (CCR)
- Cross-agent shared memory with auto-deduplication
- Output token reduction via verbosity steering and effort routing
- Agent wrapping for tools like Claude Code, Cursor, and Aider
- Local-first architecture that keeps data on your machine
Requirements, installation and quick start
Usage
Model compatibility and use cases
Headroom works with any OpenAI-compatible client via its proxy. It supports Anthropic and OpenAI-compatible endpoints for output token reduction features. It can wrap agents including Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, Cline, Continue, Goose, and OpenHands.
License and risk notes
The repository is licensed under the Apache-2.0 license.
Editorial verification 2026-08-09: repository URL, owner, description, license and repository statistics were reviewed. License metadata: Apache-2.0. README was fetched for the channel draft; re-check repository dependencies, releases and model terms before production use.
Release and maintenance
Not stated in the repository metadata.