Headroom compresses what an AI agent reads (tool outputs, logs, RAG chunks, files, and conversation history) before it reaches the model, aiming for the same answers with fewer tokens. Compression runs on the local machine, and no prompt or file content is sent elsewhere to be compressed.
A ContentRouter detects each block's content type and hands it to a compressor: SmartCrusher for JSON, which keeps error items, statistical outliers, and first and last boundaries based on field variance, CodeCompressor for AST-aware source code in Python, JS/TS, Go, Rust, Java, C/C++, C#, and PHP, and Kompress-v2-base, a Hugging Face model trained on agent traces, for prose. Only new content is compressed, so the frozen prompt prefix stays byte-identical and the provider's cache still hits. Compression is reversible: originals are cached locally, and the model calls a retrieval tool when it needs the full text.
Headroom runs as a Python or TypeScript library, as a proxy that needs no code changes, as an MCP server, or wrapped around a coding agent in one command. Wrapped agents include Claude Code, Codex, Aider, Cline, Continue, Goose, OpenHands, OpenCode, OpenClaw (as a ContextEngine plugin), Kimi CLI, and Copilot CLI. Framework integrations cover LangChain, Agno, Strands Agents, LiteLLM, the AI SDK, and the Anthropic and OpenAI SDKs. From the proxy it can also cut output tokens by steering verbosity and lowering reasoning effort on turns that only resume after a tool result.
Measured token counts on four seeded scenarios built from MCP server output formats:
| 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 grow with how repetitive the payload is, and prose or already-dense output compresses very little. Compression takes 0.21 ms at the median on a 10K-token JSON result.
Features
- Content-aware compression: routes JSON, source code, logs, search results, diffs, prose, and images to a compressor suited to each
- Reversible compression: originals stay in a local cache and the model retrieves them on demand
- Cache alignment: flags volatile content that would break a provider's prompt cache and compresses only new content
- Library, proxy, and MCP server: call compress() inline, route traffic through a proxy without code changes, or expose compress, retrieve, and stats tools over MCP
- Agent wrapping: one command wraps Claude Code, Codex, Aider, Cline, Goose, OpenHands, OpenCode, OpenClaw, and other coding agents, and another undoes it
- Framework integrations: LangChain, Agno, Strands Agents, LiteLLM, the AI SDK, ASGI middleware, and the Anthropic and OpenAI SDKs
- Cross-agent memory: one shared store across Claude, Codex, Gemini, and Grok, with agent provenance and deduplication
- Output token reduction: optional verbosity steering and effort routing trim what the model writes back
- Failure learning: headroom learn mines failed sessions and writes corrections to agent instruction files such as CLAUDE.md, AGENTS.md, or GEMINI.md
- SharedContext: passes compressed context between agents in multi-agent workflows
- Accuracy evals: a bundled suite runs GSM8K, TruthfulQA, SQuAD v2, and BFCL against a baseline
