Headroom GitHub Repository

Headroom is a local-first context compression layer that compresses tool outputs, logs, RAG chunks, files, and conversation history read by AI agents before sending them to the LLM. It is provided as a library, proxy, MCP, and headroom wrap, and combines 6 compression algorithms with a reversible structure to aim for reducing tokens by 60-95% while keeping the same answers.

The core pipeline is CacheAligner → ContentRouter → CCR. The ContentRouter determines whether content is JSON, code, or plain text and selects SmartCrusher, CodeCompressor, or Kompress-base accordingly, while CacheAligner stabilizes prefixes so that provider KV cache aligns better. CCR keeps the original locally and lets the LLM retrieve it again via headroom_retrieve when needed. It also offers cross-agent memory and headroom learn, handling state sharing between Claude, Codex, and Gemini as well as correction of failed sessions.

Measured results are also presented.

• Code search (100 results): 17,765 → 1,408 tokens, 92% reduction
• SRE incident debugging: 65,694 → 5,118 tokens, 92% reduction
• GitHub issue triage: 54,174 → 14,761 tokens, 73% reduction
• Codebase exploration: 78,502 → 41,254 tokens, 47% reduction

In benchmarks, GSM8K maintained 0.870, and TruthfulQA slightly rose from 0.530 to 0.560. It states that SQuAD v2 and BFCL each showed 97% performance, and notes that this can be reproduced with python -m headroom.evals suite --tier 1.

It also includes a compatibility matrix with Claude Code, Codex, Cursor, Aider, Copilot CLI, and OpenClaw. OpenAI-compatible clients connect via headroom proxy, and MCP-native clients connect via headroom mcp install, with support for Python 3.10+ and optional installs of [proxy], [mcp], [ml], [agno], [langchain], [evals].