Headroom Context Compression for AI Agents Pipeline

Headroom is an open-source context compression layer for AI agents and LLM applications. It sits between your AI agent (Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, or any OpenAI-compatible client) and the LLM provider and compresses everything the agent reads — tool outputs, logs, RAG chunks, files, conversation history — before it reaches the LLM. Four deployment modes: library (compress() in Python/TypeScript, inline in any app), proxy (headroom proxy --port 8787, zero code changes), agent wrap (headroom wrap claude|codex|copilot|cursor, one command), and MCP server (headroom_compress, headroom_retrieve, headroom_stats tools). All compression is reversible via CCR (Compress-Cache-Retrieve) — originals stored locally, retrievable on demand. Created by Tejas Chopra, a Senior Engineer at Netflix, after a $287 Claude Sonnet debugging bill. Apache 2.0 licensed, 58,500+ GitHub stars, 161 releases.

BUSINESS PROBLEM

According to headroom's benchmark page (July 2026), a single Claude Code debugging session on a complex SRE incident consumed 65,694 tokens in tool outputs alone. At Opus pricing ($25/MTok output), that one session costs $1.64 in output tokens — before any model thinking. A team of 10 developers running 5 sessions each per day is spending $82/day or $1,804/month on token costs that deliver zero reasoning value. Traditional approaches like manual prompt trimming are unreliable. Provider-native compression (OpenAI compaction) affects conversation history only. There was no tool that automatically compresses tool outputs, logs, RAG chunks, and files before they reach the LLM — until headroom.

WHO BENEFITS

For a developer running Claude Code daily at a 10-person startup. Situation: Monthly API bills hit $200-400 from agent usage alone. Tool outputs (JSON, logs, search results) make up 70% of context. Payoff: Headroom compresses JSON data 60-95%. Same answers, half the token bill. For a platform engineer managing multi-agent infrastructure at a 200-person company. Situation: Teams use Claude Code, Codex, and Cursor simultaneously. Each agent sends tool outputs to different provider APIs. Payoff: Headroom's cross-agent memory and shared compression store work across all agents. One setup, every agent benefits. For an ML engineer running batch inference pipelines with LLMs. Situation: RAG pipelines send 100K+ tokens of context per query. Latency and cost are both problems. Payoff: Headroom's library mode compress() reduces RAG payloads 60-95%. Latency drops as the LLM reads less. Cost per query drops proportionally.

HOW IT WORKS

Step 1. Install Headroom (2 min). Run pip install headroom-ai[all] for Python CLI, or npm install headroom-ai for TypeScript SDK. Step 2. Choose deployment mode (5 min). For zero-code setup: run headroom proxy --port 8787, then set ANTHROPIC_BASE_URL=http://127.0.0.1:8787 for Claude Code. For programmatic: from headroom import compress and call compress(messages). For one-command: run headroom wrap claude. Step 3. Test compression (5 min). Run a familiar task with and without headroom. Check headroom_stats in the MCP server or the compression log to see tokens saved per request. Step 4. Set up MCP tools (2 min). Run headroom mcp install. This adds headroom_compress (compress on demand), headroom_retrieve (retrieve originals by hash), and headroom_stats (session stats) to Claude Code's tool palette. Step 5. Enable headroom learn (optional, 5 min). Run headroom learn. It mines failed sessions, identifies patterns, and writes corrections to CLAUDE.local.md or AGENTS.md. Your agent gets better at avoiding repeated mistakes. Step 6. Monitor and tune (ongoing). Review compression logs weekly. Adjust which content types get compressed. Enable ML compression (Kompress-v2-base) for plain text if your workload has significant prose.

TOOL INTEGRATION

TOOL: Headroom v0.31.0 (Apache 2.0, 58.5K stars, 161 releases). Role: Context compression layer for AI agents. Install: pip install headroom-ai[all]. Auth: None (local-only). Cost: Free. Gotcha: ML compression (Kompress-v2-base) adds up to 50ms latency on first inference call and requires PyTorch. Skip the [ml] extra for CPU-only environments — the other compressors (SmartCrusher, CodeCompressor) cover most use cases without the overhead. TOOL: Claude Code / Codex / Cursor / Copilot CLI / Aider (any AI coding agent). Role: Target agents that send and receive compressed context. API access: Respective providers. Auth: Respective subscriptions. Cost: Existing. Gotcha: headroom wrap modifies the agent's launch script to route through the proxy. Run headroom unwrap to restore original behavior. The wrap is fully reversible. TOOL: Kompress-v2-base (HuggingFace model, Apache 2.0). Role: ML-based text compressor trained on agentic traces. Access: huggingface.co/chopratejas/kompress-v2-base. Auth: None. Cost: Free. Gotcha: Trained primarily on English agentic traces. Multilingual prompts may see worse compression ratios. For multilingual workloads, rely on SmartCrusher and CodeCompressor instead.

ROI METRICS

Metric Before (tokens) After (tokens) Source Code search (100 results) 17,765 1,408 Headroom benchmark page SRE incident debugging 65,694 5,118 Headroom benchmark page GitHub issue triage 54,174 14,761 Headroom benchmark page Codebase exploration 78,502 41,254 Headroom benchmark page

The week-1 win: install headroom in proxy mode, run one familiar debugging workflow, and check headroom_stats. The tokens-saved number is your immediate ROI. The strategic implication: context compression is infrastructure, not optimization. As AI agents handle larger codebases and more complex tool outputs, uncompressed context becomes the bottleneck on both cost and latency.

CAVEATS

1. (minor risk) Short prompts gain nothing: Content under 200 tokens or arrays under 5 items pass through unchanged. Short conversational exchanges show median 4.8% compression. Mitigation: Headroom is designed for tool-output-heavy sessions, not short chats. Do not use for quick Q&A sessions.
2. (moderate risk) Code compression is conservative: CodeCompressor is gated behind safety protections like protect_recent_code=4 (last 4 messages never compressed). Mitigation: This is intentional to avoid breaking coding workflows. Accept conservative compression for code sessions.
3. (significant risk) Kompress-base resource footprint: First-run model download + resident memory for PyTorch can be problematic in serverless or container environments. Mitigation: Disable the [ml] extra in constrained environments. SmartCrusher handles most JSON/log workloads without ML.
4. (moderate risk) Cache invalidation: If the prompt prefix changes mid-session, KV cache savings are lost and compression gains shrink. Mitigation: Headroom's CacheAligner stabilizes prefixes, but workloads with constantly shifting system prompts see less benefit.