Headroom

What It Is (confidence: medium)

Headroom is a “context compression layer for AI agents” — a library, local proxy, and MCP server that compresses tool outputs, logs, RAG chunks, files, and conversation history before they reach the LLM. Content-aware compressors (SmartCrusher for JSON, CodeCompressor for AST, Kompress-v2-base for prose) route through a ContentRouter. Runs local-first, claims “reversible” compression and “same answers, fraction of the tokens.”

Claims (confidence: medium)

• 60–95% fewer tokens for JSON data, 15–20% fewer tokens for coding agents.
• Independent survey reports 47–92% savings depending on the workflow, and notes that Headroom uses rtk-rust-token-killer under the hood for shell output — so they are not two fully separate layers.
• Modes: compress(messages) library (Python/TS), headroom proxy --port 8787 drop-in proxy, headroom_compress / headroom_retrieve / headroom_stats MCP tools.
• Wrapping an agent launches a local proxy + Serena (semantic code navigation) and points the agent at headroom.

Output Token Reduction (confidence: medium)

Unlike input-only compressors, Headroom also trims what the model writes back: drops “Great, let me…” preambles, re-printed code, and skips deep “thinking” on routine steps via proxy-level shaping (reasoning_effort on OpenAI, thinking.budget_tokens / output_config.effort on Anthropic). It explicitly frames this on the 5× output-cost ratio on Opus-class models — the same asymmetry RTK’s issue #582 exposed.

Implications (confidence: medium)

Headroom is the direct descendant of the RTK lesson: input compression alone is insufficient, so it adds an output-shaper. Its “reversible” claim (CCR reversible compression) addresses the information-loss concern that made compressed input expensive in RTK’s case. The JSON-specific 60–95% figures target a different regime (structured tool data) than prose compression.

Open Questions

• Whether “reversible” compression truly preserves information at 95% reduction for adversarial cases.
• Whether the proxy’s output shaping degrades answer quality on tasks that legitimately need long reasoning.

Related

rtk-rust-token-killer — input-only predecessor; the contradiction Headroom’s output shaper addresses (also its shell-output engine) token-optimizer-mcp — caching + routing optimizer, different mechanism token-usage-reduction — context-engineering levers this tool automates token-waste-sources — the diagnostic taxonomy positioning Headroom for messy multi-source context claude-code-system-prompt — wrapped-agent target

Sources

• raw/external/github-com-headroom-cbd05f4e.md
• raw/prompts/articles/reduce-wasted-tokens.md