headroom
Proxy-level context compression for AI agents. Compresses tool outputs, logs, RAG chunks, files, and conversation history BEFORE they reach the LLM. 60-95% fewer tokens for JSON, 15-20% fewer for codi
SKILL.mdskills/headroom/SKILL.md
GitHubHeadroom
Proxy-level compression. Sits between tools and LLM. Strips tokens before model sees them. Different layer than caveman (prose) or ponytail (code).
What it does
Compresses everything agent reads — tool outputs, logs, RAG chunks, files, conversation history — before LLM. Same answers, fraction of tokens.
Compression layers
| Layer | What | Savings |
|---|---|---|
| SmartCrusher | JSON data | 60-95% |
| CodeCompressor | AST-aware code | high |
| Kompress-v2-base | Prose/text (HF model) | moderate |
| CacheAligner | Detects volatile content that busts KV cache | warns, never rewrites |
| CCR | Reversible — originals cached for retrieval | lossless on demand |
Modes
- Library —
compress(messages)inline in Python/TypeScript app - Proxy —
headroom proxy --port 8787, zero code changes, any language - Agent wrap —
headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcodein one command - MCP server —
headroom_compress,headroom_retrieve,headroom_statsfor any MCP client - Cross-agent memory — shared store across Claude, Codex, Gemini, Grok, auto-dedup
- headroom learn — mines failed sessions, writes corrections to CLAUDE.local.md / AGENTS.md / GEMINI.md / GROK.md
Install
# Python CLI (recommended — ships headroom command)
uv tool install --python 3.13 "headroom-ai[all]"
# or
pip install "headroom-ai[all]"
# TypeScript SDK only (no CLI)
npm install headroom-ai
Requires Python 3.10+. Granular extras: [proxy], [mcp], [ml], [code], [memory], [vector], [relevance], [image], [agno], [langchain], [evals], [pytorch-mps].
Quick start
headroom deploy # turnkey local deployment + agent config
headroom wrap claude # wrap a coding agent
headroom proxy --port 8787 # drop-in proxy, zero code changes
headroom doctor # health check — confirms routing works
headroom perf # performance report
headroom dashboard # live savings dashboard (proxy must run)
MCP config (for Codex or any MCP client)
[mcp_servers.headroom]
command = "/absolute/path/from/command-v/headroom"
args = ["mcp", "serve"]
Use command = "headroom" only when client PATH includes uv tool dir.
MCP tools
headroom_compress— compress messages/outputs before sending to LLMheadroom_retrieve— fetch original (uncompressed) content on demandheadroom_stats— compression statistics
Proven savings (real workloads)
| 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: GSM8K ±0.000, TruthfulQA +0.030, SQuAD v2 97%, BFCL 97%.
When to use
- Tool outputs bloating context (grep with 100 results, long logs, big JSON)
- RAG chunks eating token budget
- Conversation history growing large
- Cross-agent memory dedup needed
- Want reversible compression (not lossy)
When NOT to use
- Already using rtk for CLI command compression (overlaps — pick one layer)
- Output prose compression only (use caveman-mode)
- Code minimization only (use ponytail)
- Tiny context, no budget pressure
Pair with
- caveman-mode — headroom cuts input tokens, caveman cuts output tokens. Both = max savings.
- ponytail — headroom compresses what agent reads, ponytail minimizes what agent writes (code).
- caveman-ponytail — all three together = brain big, mouth small, code small, context small.
Boundaries
Headroom = input/context compression. Does not change what model says (pair with caveman) or what code gets written (pair with ponytail). Reversible via CCR — originals always retrievable.
Skill Chains
- For compress bridge session output before agent ingestion ->
[cross-runtime-bridge](sessions)