Headroom

What It Does

Headroom compresses everything an AI agent reads before it reaches the LLM: tool outputs, logs, RAG chunks, files, and conversation history. It ships as a Python library (compress(messages)), a local HTTP proxy (headroom proxy --port 8787), an MCP server (three tools: headroom_compress, headroom_retrieve, headroom_stats), a one-command agent wrapper (headroom wrap claude), and an OpenClaw plugin. The core is written in Rust (66K lines across 175 files) with Python bindings (407 modules) and a TypeScript SDK. It targets developers and teams running AI coding agents who want lower token costs without rewriting their tooling.

The Good

Verified 91% compression on JSON tool outputs. In hands-on testing, a 500-item JSON array of TypeScript widget metadata (87,499 chars, 27,443 tokens) compressed to 8,454 chars (2,407 tokens). The SmartCrusher algorithm preserved all ERROR-severity entries while dropping redundant INFO rows. The CompressResult object reports compression_ratio: 0.912 and transforms_applied: ['router:smart_crusher:0.05'], giving concrete evidence of which algorithm ran and its confidence threshold.

Verified 85% compression on structured logs. A 500-line log file with interleaved ERROR/WARN/INFO lines (43,603 chars, 16,539 tokens) compressed to 6,466 chars (2,526 tokens). The log compressor kept error lines verbatim while summarizing repetitive INFO patterns. The transform log shows router:log:0.15, confirming log-specific routing.

5,544 test functions across 355 test files (129K lines of test code). This is one of the largest test suites in the agent tooling ecosystem. Tests cover compression roundtrips, cache behavior, proxy lifecycle, MCP tool registration, memory isolation, WebSocket handling, and multi-provider routing. The CI badge on the README points to a GitHub Actions workflow. Codecov is integrated for coverage tracking.

Reversible compression via CCR (Compress-Cache-Retrieve). Originals are never deleted. The LLM can call headroom_retrieve with a hash key to get the full uncompressed content back on demand. This is the critical design decision that distinguishes Headroom from naive truncation. The MCP server exposes this as a standard tool any MCP client can invoke.

Six compression algorithms with automatic content routing. The ContentRouter detects content type and selects the right compressor: SmartCrusher for JSON arrays (statistical selection, preserves anomalies and boundaries), CodeCompressor for code (AST-aware via tree-sitter), Kompress-base for prose (ML model on HuggingFace), a log compressor for structured logs, a search result compressor, and an image compressor. Users do not need to pick algorithms manually.

Unmatched agent ecosystem coverage. The headroom wrap command supports Claude Code, Codex, Cursor, Aider, Copilot CLI, and OpenClaw with a single command. The MCP server works with any MCP-compatible host. SDK wrappers exist for Anthropic, OpenAI, Vercel AI SDK, LangChain, Agno, Strands, and LiteLLM. The OpenClaw plugin includes auto-start proxy detection and gateway provider routing. No other token efficiency tool comes close to this breadth.

Thorough documentation infrastructure. The repo ships llms.txt and links to a hosted llms-full.txt for LLM consumption. The wiki/ directory contains 30 focused markdown pages covering architecture, benchmarks, configuration, each integration, troubleshooting, and limitations. A docs site with search is linked from the README. The CHANGELOG follows Keep a Changelog format with semantic versioning.

The Bad

Heavy dependency footprint with [all] extras. The full install (pip install "headroom-ai[all]") pulls in torch (2.12.0, ~2 GB), transformers, onnxruntime, opencv, sentence-transformers, scikit-learn, and 100+ transitive dependencies. The base install is lighter (tiktoken, pydantic, click, rich, litellm), but most users will want at least the [proxy] extras which include fastapi, uvicorn, and websockets. For developers who already have ML dependencies installed this is not an issue, but for teams wanting a minimal agent tool it is a significant install.

Code compression returned 0% savings in testing. When compressing a 300-entry code search result (81,348 chars) as a tool message, the transform log reported router:protected:recent_code and produced no compression. The benchmarks page confirms this: grep results and Python source show 0% compression because "these are already compact structured formats." This is documented behavior, but it means Headroom's headline "60-95% fewer tokens" does not apply to code-heavy workflows where the tool output is already structured code. Users with code-review or refactoring agents may see lower savings than advertised.

The proxy requires API keys for live testing. Headroom's proxy mode (the most common deployment) sits between the agent and the LLM provider. Testing it end-to-end requires valid Anthropic or OpenAI API keys. The headroom proxy command starts successfully and reports healthy, but without upstream credentials it cannot demonstrate actual compression on real agent traffic. This is inherent to the architecture, not a bug, but it limits what a hands-on review can verify.

No SKILL.md or agent-native skill format. Headroom does not ship as a Hermes skill, Cursor rule, or SKILL.md-compatible package. It is a standalone tool with its own install and configuration. Agent users must either use the MCP server integration or the headroom wrap command to get compression in their workflow. This is a minor gap given the MCP and wrap support, but it means there is no zero-config "just drop this skill file" option.

Smoke Test Results

All tests run on macOS (host), aarch64, Python 3.11.14 in a clean venv with headroom-ai[all] v0.22.4.

Run A. Fresh venv, full install

$ python3.11 -m venv /tmp/headroom-test-venv
✅ venv created

$ /tmp/headroom-test-venv/bin/pip install "headroom-ai[all]"
✅ Installed headroom-ai-0.22.4 + 200+ deps (torch, transformers, etc.)

$ /tmp/headroom-test-venv/bin/headroom --version
✅ headroom, version 0.22.4

$ /tmp/headroom-test-venv/bin/headroom --help
✅ 6 subcommands listed: proxy, mcp, wrap, memory, learn, init

$ /tmp/headroom-test-venv/bin/headroom wrap --help
✅ 5 agents supported: claude, codex, cursor, aider, copilot

$ /tmp/headroom-test-venv/bin/headroom mcp status
✅ MCP SDK: Installed, Claude Config: No config file, Proxy: Not running

Pass rate: 6 of 6. CLI installs and all subcommands respond correctly.

Run B. Functional verification (compress API)

$ compress([tool msg with 500-item JSON array], model="gpt-4")
✅ tokens_before=27,443, tokens_after=2,407, savings=91.2%
 transforms: router:protected:user_message, router:smart_crusher:0.05

$ compress([tool msg with 500-line log], model="gpt-4")
✅ tokens_before=16,539, tokens_after=2,526, savings=84.7%
 transforms: router:protected:user_message, router:log:0.15

$ compress([tool msg with 300-entry code search], model="gpt-4")
❌ tokens_before=21,835, tokens_after=21,835, savings=0.0%
 transforms: router:protected:user_message, router:protected:recent_code

$ compress([user msg with JSON], model="gpt-4")
❌ tokens_before=54,909, tokens_after=54,909, savings=0.0%
 transforms: router:protected:user_message
 (user messages are protected by design)

Pass rate: 2 of 4 functional claims verified. JSON and log compression match or exceed advertised ranges. Code compression is 0% (documented limitation for structured code). User message protection is by design.

What the runs tell you

The CLI installs cleanly and all subcommands work. The core compression claim (60-95% savings) is verified for JSON tool outputs and structured logs, the two most common high-volume content types in agent workflows. Code compression does not kick in for already-compact code search results, which is documented but may surprise users expecting universal savings. The MCP server installs and reports status correctly, though end-to-end proxy compression requires live API keys.

Setup Walkthrough

1. Install with pip: pip install "headroom-ai[proxy]" (includes MCP tools and proxy server). Add [all] if you want ML-based text compression and memory features.
2. Verify the install: headroom --version should print headroom, version 0.22.4.
3. For MCP integration with Claude Code: headroom mcp install registers the three MCP tools automatically.
4. For proxy mode: headroom proxy --port 8787 starts the local proxy. Point your agent at it: ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude.
5. For one-command wrapping: headroom wrap claude configures Claude Code to route through Headroom automatically.
6. Check savings: headroom stats shows token savings from the current session.

Gotcha: The [all] install includes torch (~2 GB). If you only need JSON and log compression, pip install "headroom-ai[proxy]" is sufficient and much smaller.

Alternatives

1. evilayman/opencode-raven - Hard MCP rerouter that trims tool responses before they reach the agent's context. Lighter weight than Headroom (no ML models), but only filters, it does not compress. Good for targeted context management without the heavy install.
2. LLMLingua (Microsoft) - Prompt compression via small language models. Academic origin with published benchmarks. Compresses prompts rather than tool outputs. No agent integration, no MCP server, no proxy mode. Useful as a comparison baseline.
3. Native provider compaction (Anthropic prompt caching, OpenAI automatic truncation) - Built into each provider's API with zero install. No cross-agent memory, no reversible retrieval, no content-type awareness. Worth trying first if you only use one provider and do not need the features Headroom adds on top.