Headroom — Token Compression for AI Agents
Headroom compresses AI agent inputs by 60-95% for JSON and 15-20% for coding agents — reversibly, with zero code changes.
Every AI coding agent faces the same problem: token costs. Every tool call output, every file read, every log snippet gets stuffed into the context window and billed by the token. For teams running Claude Code, Cursor, or Codex on large codebases, this adds up to real money — and real context-window headaches.
Headroom is an open-source, local-first token-compression layer that sits between your AI agent and the LLM provider, compressing everything an AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the API.
What is Headroom?#
Headroom is a context optimization engine that achieves 60–95% token savings on JSON data and 15–20% token savings for coding agents while preserving identical answers and behavioral accuracy. It’s fully reversible — originals are cached locally and can be retrieved on demand when the LLM needs the full data back.
It works in four modes:
- Proxy mode — zero-code-change drop-in proxy (
headroom proxy --port 8787) - Agent wrap — one-command wrapper for Claude Code, Codex CLI, Cursor, and 18+ other agents
- Python/TypeScript library — inline
compress()calls in your code - MCP server — expose compression tools to any MCP-compatible agent
The project is built with a Python core + Rust extensions (via PyO3), giving it both flexibility and native performance for AST parsing and compression.
Why Headroom Matters#
Token Savings Are Real#
| Data type | Compression | Method |
|---|---|---|
| JSON tool outputs | 60–95% | SmartCrusher — universal JSON compressor |
| Code files | AST-aware | CodeCompressor for Python, JS/TS, Go, Rust, Java, C/C++, Perl |
| Prose / text | v2 transformer | Kompress-v2-base (trained on agentic traces) |
| Images | 40–90% | ML router + OCR (RapidOCR/SigLIP) |
| Coding agent sessions | 15–20% | Combination of all compressors |
Provider KV-Cache Safe#
Headroom’s Live-Zone Compression compresses only incoming new bytes (fresh tool output, latest turn) while keeping the frozen prefix byte-identical. This is critical because provider KV-caches (like Anthropic prompt caching) cache on byte-exact prefix matches. If you alter the prefix, you bust the cache. Headroom never does.
Reversible Compression#
When an LLM needs trimmed data back, Headroom’s CCR (Cached Context Retrieval) system stores originals locally in SQLite or Redis and injects lightweight retrieval tags (<<ccr:HASH>>). The agent can call headroom_retrieve to fetch the original payload on demand.
Output Token Reduction Too#
Headroom doesn’t just compress what you send — it also trims what the model writes back through:
- Verbosity steering — appends brief instructions to prompts
- Effort routing — dials down reasoning/thinking budgets on routine steps like reading files
Supported Integrations#
18+ AI coding agents (via headroom wrap):
Claude Code, Codex CLI, Cursor, Aider, GitHub Copilot CLI, OpenCode, Cline, Continue, OpenClaw, Goose, OpenHands, Mistral Vibe, Oh My Pi, and ZCode.
SDKs & Frameworks: Anthropic SDK, OpenAI SDK, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands Agents SDK, FastAPI/ASGI middleware
Installation#
# Python (recommended via uv)
uv tool install --python 3.13 "headroom-ai[all]"
# Or via pip
pip install "headroom-ai[all]"
# TypeScript SDK
npm install headroom-aiQuick Start#
Proxy mode (zero code changes)#
headroom proxy --port 8787
# Point your LLM client to http://localhost:8787Agent wrap mode#
headroom wrap claude
# Claude Code now sends compressed inputs automatically
headroom unwrap claude # To undoInline library usage#
from headroom import compress
compressed = compress(large_json_payload)How It Works#
Agent / App → Headroom Proxy / Library → LLM Provider- Input received — incoming prompt messages or tool payload streams are intercepted
- CacheAligner — inspects and warns about volatile content that would bust provider KV-cache prefixes
- ContentRouter — detects content type (Magika/heuristic analysis) and selects the optimal compressor
- CCR — stores original verbose strings locally, injects retrieval tags
- Forwards optimized payload to the LLM upstream
The headroom learn Feature#
Headroom mines past failed/frustrated sessions locally and auto-writes corrections into agent memory config files (CLAUDE.local.md, AGENTS.md). This means the agent gets smarter about its own mistakes over time.
Cross-Agent Memory#
A shared, deduplicated context store that works across multiple AI coding agents on the same machine. Claude Code, Cursor, and Codex can all share a common memory without duplicating context.
Comparison#
| Feature | Headroom | Native provider compaction | Prompt caching proxies |
|---|---|---|---|
| Compression ratio | 60–95% (JSON), 15–20% (code) | Variable (drops context) | None (caches only) |
| Reversible | ✅ CCR retrieval | ❌ Drops context | ❌ |
| KV-cache safe | ✅ CacheAligner | ✅ Same provider | ✅ Same provider |
| Output reduction | ✅ Verbosity steering + effort routing | ❌ | ❌ |
| Cross-agent memory | ✅ Shared context store | ❌ | ❌ |
| Self-learning | ✅ headroom learn | ❌ | ❌ |
| Agent integrations | 18+ agents | Varies | Varies |
| Code changes | Zero (proxy/wrap) | None | None |
Summary#
Headroom solves a fundamental inefficiency in AI-assisted development: sending verbose, uncompressed data to LLM APIs. With 60–95% compression on JSON, reversible retrieval, KV-cache-safe compression, and zero-code-change integration, it’s one of the most practical cost-saving tools for any team using AI coding agents at scale.
Apache 2.0 licensed, local-first, and extensible via Python + Rust — Headroom is a drop-in upgrade for any AI agent workflow.