Headroom

Headroom is an open-source context compression system designed specifically for AI agents. It compresses everything your agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. The result is the same quality of answers at a fraction of the token cost, typically reducing token usage by 60–95% for JSON data and 15–20% for coding agents.

Created by Tejas Chopra, Headroom operates as a library, proxy, agent wrapper, and MCP server. It is licensed under Apache 2.0 and hosted on GitHub at github.com/chopratejas/headroom. Compression is reversible through a CCR (Cache, Compress, Retrieve) system that stores originals locally for on-demand retrieval.

Python (recommended — includes the CLI):

pip install "headroom-ai[all]"

TypeScript SDK (library only):

npm install headroom-ai

Requires Python 3.10+ for the full CLI. Granular extras available: [proxy], [mcp], [ml], [code], [memory], [langchain], [evals], and more.

Headroom offers multiple integration modes to fit any workflow:

Mode	Description
Library	from headroom import compress — inline compression in Python or TypeScript
Proxy	headroom proxy --port 8787 — drop-in transparent proxy, zero code changes
Agent Wrap	headroom wrap claude — automatically wrap a coding agent with compression
MCP Server	Provides headroom_compress, headroom_retrieve, headroom_stats tools

Headroom uses a multi-stage compression pipeline that intelligently selects the right compressor for each type of content:

• ContentRouter — Detects content type (JSON, code, prose, logs) and selects the optimal compressor
• SmartCrusher — Optimized for JSON data, achieving 60–95% token reduction while preserving all data
• CodeCompressor — AST-based compression for source code that preserves structure and semantics
• Kompress-v2-base — A dedicated ML model (on Hugging Face) for general text compression
• CacheAligner — Stabilizes prefix patterns so provider KV caches produce maximum savings

All compression is reversible through the CCR (Cache, Compress, Retrieve) system. Original content is cached locally, and the LLM can call headroom_retrieve if it needs the full, uncompressed version.

Headroom's wrap command automatically configures popular AI coding agents to route through Headroom's compression proxy. Supported agents include Claude Code, Codex, Copilot, Cursor, Aider, OpenCode, Cline, Continue, Goose, OpenHands, OpenClaw, and Vibe. Use headroom unwrap <tool> to revert the configuration.

The wrap system also enables output token reduction, which trims what the model writes back (not just what you send). It drops ceremony text, restated code blocks, and skips deep thinking on routine steps, reducing the total tokens consumed both ways.

Headroom includes a cross-agent memory system that maintains a shared knowledge store across Claude, Codex, Gemini, and other agents. It automatically deduplicates stored information and can mine failed sessions with headroom learn to write corrections to agent instruction files like CLAUDE.local.md, AGENTS.md, or GEMINI.md.

Headroom demonstrates significant token savings while preserving accuracy on standard benchmarks:

Workload	Before	After	Savings
Code Search (100 results)	17,765	1,408	92%
SRE Incident Debugging	65,694	5,118	92%
GitHub Issue Triage	54,174	14,761	73%
Codebase Exploration	78,502	41,254	47%

Accuracy preserved on GSM8K (math), TruthfulQA (factual), SQuAD v2 (QA), and BFCL (tools) benchmarks with no significant degradation. Run python -m headroom.evals suite --tier 1 to reproduce.