Headroom

Headroom compresses what an AI agent reads — tool outputs, logs, retrieval chunks, files, and conversation history — before the request reaches the model. Compression runs on the local machine, and originals are cached locally so the model can pull back the full text on demand through a retrieval tool.

There are four ways to apply it: a library (compress(messages) in Python or TypeScript), a proxy that needs no code changes, a one-command wrapper around a coding agent (headroom wrap claude, undone with headroom unwrap), and an MCP server exposing headroomcompress, headroomretrieve, and headroom_stats. A shared cross-agent memory store spans Claude, Codex, Gemini, and Grok with automatic deduplication, and headroom learn mines failed sessions into corrections written to an agent instruction file.

A content router detects the content type and selects a compressor: SmartCrusher for JSON, an AST-aware CodeCompressor for Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, and Perl, and the Kompress-v2-base model for prose. A CacheAligner flags volatile content that would break a provider key-value cache prefix without rewriting prompts, and only new bytes are compressed so the frozen prefix stays byte-identical.

Four scenarios built from real MCP server output formats are measured with the provider tokenizer and the shipped compress():

Scenario	Before	After	Saved
Code search (100 results)	17,199	13,597	21%
SRE incident debugging	55,957	24,340	57%
Codebase exploration	58,801	33,895	42%
GitHub issue triage	46,067	32,429	30%

Savings scale with how repetitive the payload is; prose and already-dense output compress very little, and blocks under mininputwords come back byte-identical. Compression is measured at 0.21 ms at the median on a 10K-token JSON search result and 1.4 ms at 100K tokens. On accuracy evaluations at N=100, GSM8K matches the baseline at 0.870 and TruthfulQA moves 0.030, a delta inside the confidence interval.

Features

• Four integration modes: library call, drop-in proxy, agent wrapper, or MCP server
• Reversible compression: originals are cached locally and retrieved on demand through CCR
• Content-aware routing: separate compressors for JSON, source code, and prose
• Cache alignment: volatile content is flagged rather than rewritten, so provider prompt caches keep hitting
• Cross-agent memory: one shared store across Claude, Codex, Gemini, and Grok, with deduplication
• Output token reduction: optional verbosity steering and effort routing trim what the model writes back, for Anthropic and OpenAI-compatible endpoints
• Savings reporting: headroom savings, headroom output-savings with a confidence range, a live dashboard, and an optional unshaped holdout for a measured figure
• Agent wrapping: covers Claude Code, Codex, Grok CLI, Aider, Copilot CLI, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, and others
• Framework adapters: LangChain, Agno, Strands, LiteLLM, the Vercel AI SDK, and ASGI middleware
• Session learning: headroom learn writes corrections and a verbosity level from past sessions