headroom

• ContentRouter — detects content type, selects the right compressor
• SmartCrusher / CodeCompressor / Kompress-base — compress JSON, AST, or prose
• CacheAligner — stabilizes prefixes so provider KV caches actually hit
• CCR — stores originals locally; LLM calls headroom_retrieve if it needs them

→ Architecture · CCR reversible compression · Kompress-base model card

Get started (60 seconds)

# 1 — Install
pip install "headroom-ai[all]"          # Python
npm install headroom-ai                 # Node / TypeScript

# 2 — Pick your mode
headroom wrap claude                    # wrap a coding agent
headroom proxy --port 8787              # drop-in proxy, zero code changes
# or: from headroom import compress      # inline library

# 3 — See the savings
headroom stats

Granular extras: [proxy], [mcp], [ml], [agno], [langchain], [evals]. Requires Python 3.10+.

Proof

Savings on real agent 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 on standard benchmarks:

| Benchmark | Category | N | Baseline | Headroom | Delta | |------------|----------|----:|---------:|---------:|------------| | GSM8K | Math | 100 | 0.870 | 0.870 | ±0.000 | | TruthfulQA | Factual | 100 | 0.530 | 0.560 | +0.030 | | SQuAD v2 | QA | 100 | — | 97% | 19% compression | | BFCL | Tools | 100 | — | 97% | 32% compression |

Reproduce: python -m headroom.evals suite --tier 1 · Full benchmarks & methodology

Agent compatibility matrix

| Agent | headroom wrap | Notes | |-------------|:---------------:|----------------------------------| | Claude Code | ● | --memory · --code-graph | | Codex | ● | shares memory with Claude | | Cursor | ● | prints config — paste once | | Aider | ● | starts proxy + launches | | Copilot CLI | ● | starts proxy + launches | | OpenClaw | ● | installs as ContextEngine plugin |

Any OpenAI-compatible client works via headroom proxy. MCP-native: headroom mcp install.

When to use · When to skip

Great fit if you…

• run AI coding agents daily and want savings without changing your code
• work across multiple agents and want shared memory
• need reversible compression — originals always retrievable via CCR

Skip it if you…

• only use a single provider's native compaction and don't need cross-agent memory
• work in a sandboxed environment where local processes can't run

| Your setup | Hook in with | |------------------------|------------------------------------------------------------------| | Any Python app | compress(messages, model=…) | | Any TypeScript app | await compress(messages, { model }) | | Anthropic / OpenAI SDK | withHeadroom(new Anthropic()) · withHeadroom(new OpenAI()) | | Vercel AI SDK | wrapLanguageModel({ model, middleware: headroomMiddleware() }) | | LiteLLM | litellm.callbacks = [HeadroomCallback()] | | LangChain | HeadroomChatModel(your_llm) | | Agno | HeadroomAgnoModel(your_model) | | Strands | Strands guide | | ASGI apps | app.add_middleware(CompressionMiddleware) | | Multi-agent | SharedContext().put / .get | | MCP clients | headroom mcp install |

• SmartCrusher — universal JSON: arrays of dicts, nested objects, mixed types.
• CodeCompressor — AST-aware for Python, JS, Go, Rust, Java, C++.
• Kompress-base — our HuggingFace model, trained on agentic traces.
• Image compression — 40–90% reduction via trained ML router.
• CacheAligner — stabilizes prefixes so Anthropic/OpenAI KV caches actually hit.
• IntelligentContext — score-based context fitting with learned importance.
• CCR — reversible compression; LLM retrieves originals on demand.
• Cross-agent memory — shared store, agent provenance, auto-dedup.
• SharedContext — compressed context passing across multi-agent workflows.
• headroom learn — plugin-based failure mining for Claude, Codex, Gemini.

Headroom exposes one stable request lifecycle across compress(), the SDK, and t