Headroom

Why pick it

You burn tokens on tool dumps, logs, RAG chunks, and long agent history and want a local compression layer that sits in front of the LLM — same job, fewer tokens. Headroom (Apache-2.0) routes content by type (JSON, code AST, prose), caches originals for on-demand retrieve (CCR), and can wrap common coding agents with almost no app changes.

Claimed ranges from their docs: large JSON/tool workloads often drop hard; coding-agent sessions more modestly. Accuracy is measured on public suites (GSM8K, TruthfulQA, tool-calling) rather than only demo clips.

What you get

• Library — compress(messages) in Python; TypeScript SDK on npm (headroom-ai, library only).
• Proxy — headroom proxy --port 8787 for OpenAI/Anthropic-compatible clients with zero code changes.
• Agent wrap — headroom wrap claude|codex|grok|copilot|opencode|… starts proxy + agent config; headroom unwrap <tool> undoes durable wrap.
• MCP — headroom_compress, headroom_retrieve, headroom_stats via headroom mcp serve.
• Content-aware stack — SmartCrusher (JSON), CodeCompressor (AST), Kompress-v2-base (text, HF); CacheAligner warns on KV-cache busting content without rewriting prompts.
• Cross-agent memory + headroom learn — shared store; mine failed sessions into CLAUDE.local.md / AGENTS.md / etc.
• Optional output shaper — trim model verbosity / dial effort on routine tool-resume turns (HEADROOM_OUTPUT_SHAPER=1).
• Ops — headroom doctor, perf, dashboard, deploy.

Why it over the others

vs provider-native compaction (e.g. OpenAI conversation compaction) — Headroom is local, multi-content-type, multi-agent, and reversible (CCR). Provider tools stay inside one vendor.

vs hosted compressors — data stays on your machine; no ship-all-context to a third-party compress API.

vs shell-only output rewriters (e.g. RTK) — Headroom targets the full agent context path (tools, files, history), not only CLI stdout wrappers.

When it's not the right pick

• You already live inside one provider’s native compaction and do not need cross-agent memory.
• The environment forbids local long-running processes (strict sandboxes with no proxy).
• You only need a one-line library call in TS without the Python CLI — use the npm SDK, not pip for the headroom binary.

Quick start

uv tool install --python 3.13 "headroom-ai[all]"   # preferred for the CLI
pip install "headroom-ai[all]"                    # also ships the headroom CLI
headroom wrap claude                              # or: headroom proxy --port 8787
headroom doctor

Python 3.10+ (3.13 recommended for $ savings tiles via LiteLLM). npm headroom-ai is SDK only — no headroom command.

Docs: headroom-docs.vercel.app · repo: headroomlabs-ai/headroom.