Headroom: The Context Compression Layer for AI Agents
Compress tool outputs, logs, files, and RAG chunks before they reach the LLM, saving 15-20% tokens for coding agents and 60-95% for JSON, with identical answers.
Evidence shows: local-first operation, data stays on machine; passthrough mode for sensitive content; security policy documents no credential storage; dependencies have CVE fixes and constraints. Deductions: least privilege not explicitly addressed; user confirmation unclear for wrap operations; external effects (modifying user config) not fully documented; publisher identity unverified, source attribution unclear.
Evidence shows: README and pyproject.toml descriptions consistent; feature list clear; dependencies have version constraints and CVE fixes; CI tests and error handling mentioned. Deductions: no specific failure message examples; dependency availability not fully verified (e.g., model downloads rely on external services).
Evidence shows: clear target audience (developers, teams); multiple usage scenarios (library, proxy, MCP); capability boundaries clear (supports many agents and frameworks); trigger conditions explicit (wrap, proxy commands); environment fit good (Python 3.10+, multiple OS). Deductions: not all environment limitations detailed (e.g., Windows support limited).
Evidence shows: clear information architecture with docs and llms.txt; detailed install notes; stable naming (headroom-ai); examples and FAQ present; known limitations mentioned (e.g., sandbox); Apache-2.0 license; version and changelog; maintenance responsibility stated (community support). Deductions: publisher identity unverified, maintenance responsibility unclear.
Evidence shows: high output usability (originals retrievable after compression); clear marginal value (token savings); cost-benefit supported by data (savings percentages). Deductions: no independent verification; cost-benefit data may come from internal tests.
Evidence shows: performance data in README has benchmarks and reproduction commands; multiple sources (README, pyproject, CI) corroborate; facts and inferences separated (e.g., output savings are estimates). Deductions: limited cross-source verification; no third-party independent verification.
- The agent modifies user configuration files (e.g., CLAUDE.local.md); ensure backups or know how to undo.
- Depends on external model downloads (e.g., HuggingFace); may not work in offline or restricted network environments.
- Publisher identity is unverified; use with caution and review code and dependencies for security.
What does this agent do, and when should you use it?
Headroom is a local-first context compression layer for AI agents that reduces the number of tokens sent to an LLM without changing the answers. It provides Python and TypeScript libraries, a drop-in proxy, an MCP server, and cross-agent memory. The core pipeline uses a ContentRouter to detect content type, then compresses with SmartCrusher for JSON, CodeCompressor (AST-aware) for code, and Kompress-v2-base for prose. Compression is reversible via a CCR mechanism that caches originals locally, retrievable on demand. The project supports integration with coding agents like Claude Code, Codex, Copilot, and Cursor through a proxy, and transparently handles Anthropic and OpenAI-compatible APIs. It also includes headroom learn to mine failed sessions and write corrections to memory files like CLAUDE.md.
Headroom performs several concrete operations before content reaches the LLM. As a library, it offers compress() to process messages directly. As a proxy, headroom proxy --port 8787 runs a drop-in proxy for any client. As a wrapper, headroom wrap claude launches a local proxy, installs semantic code navigation via Serena, and configures the agent to route through Headroom. It uses a ContentRouter to classify input, then compresses with SmartCrusher (JSON), CodeCompressor (AST), or Kompress-v2-base (text). Output-side token reduction includes verbosity steering and reduced thinking effort, enabled via HEADROOM_OUTPUT_SHAPER. It serves an MCP server with tools like headroom_compress, headroom_retrieve, and headroom_stats. It mines failed sessions with headroom learn and writes corrections to CLAUDE.md, AGENTS.md, or GEMINI.md.
- A developer using Claude Code or Cursor daily wants to reduce context tokens for tool outputs by 15-20% without changing answers.
- An SRE dealing with huge JSON responses uses SmartCrusher to achieve 60-95% token reduction.
- A RAG pipeline engineer compresses large document chunks before sending them to the LLM.
- A team using multiple agents (Claude, Codex, Gemini) shares memory across them with cross-agent memory.
- A CI environment runs coding agents and wants to cut token costs for automated workflows.
- A developer integrates with Anthropic or OpenAI APIs transparently via the proxy or SDK adapters.
What are this agent's strengths and limitations?
- Local-first and reversible: data stays on your machine, and originals are retrievable via CCR.
- Content-aware compression: uses specialized compressors for JSON, code, and text.
- Agent-agnostic: supports Claude Code, Codex, Copilot, Cursor, and more via proxy and OpenAI compatibility.
- Output-side token reduction: shrinks what the model writes back, including verbosity steering and thinking budget cuts.
- Cross-agent shared memory: shares context across multiple agents with automatic deduplication.
- Setup overhead: wrapping an agent requires a local proxy and configuration, which may require debugging.
- Python version requirements: needs Python 3.10+ but 3.13+ for full dollar savings with LiteLLM.
- CPU requirement: x86 hosts need AVX2 for ONNX-backed features, limiting some older VMs.
- Performance overhead: compression adds latency to each request.
- Documented limitations: some paths are noted as smoke-tested but not fully validated (e.g., Windows/Linux credential storage).
How do you install or deploy this agent?
Headroom installs as a Python tool via pip or uv, with a TypeScript SDK. The Python CLI provides full features; the TypeScript SDK is library-only.
How do you use this agent?
After installation, run Headroom in your preferred mode. Start a zero-code proxy with headroom proxy --port 8787. Wrap a coding agent with headroom wrap claude. Use headroom deploy for a turnkey setup. Verify with headroom doctor.