headroom

Headroom is a context compression layer for AI agents. It compresses everything an agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM, with the goal of keeping answers intact while reducing token usage. Compression runs locally; prompts and file contents are not sent elsewhere for compression. Capabilities: - Library: `compress(messages)` in Python or TypeScript, usable inline in any application. - Proxy: `headroom proxy --port 8787` is a drop-in local proxy requiring no code changes and works with any OpenAI-compatible client. - Agent wrapper: `headroom wrap` supports Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Kimi CLI, ZCode, and others; `headroom unwrap` reverses the setup. - MCP server: exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` tools for any MCP client. - Cross-agent memory: a shared, deduplicated store across Claude, Codex, Gemini, and Grok. - `headroom learn`: mines failed sessions and writes corrections to `CLAUDE.local.md` (default, gitignored) or other agent instruction files. - Output token reduction: optional proxy-side verbosity steering and effort routing to trim tokens the model writes back, not just what is sent. - Reversible compression (CCR): originals are cached locally and retrieved on demand via `headroom_retrieve`. How it works: a ContentRouter detects content type and selects a compressor — SmartCrusher for JSON, CodeCompressor (AST-aware, supporting Python, JS/TS, Go, Rust, Java, C/C++, and Perl), and Kompress-v2-base (a Hugging Face model trained on agentic traces) for prose. CacheAligner flags volatile content that would bust a provider KV-cache prefix without rewriting prompts; live-zone compression keeps the frozen prefix byte-identical so provider caches survive. Framework adapters are provided for Anthropic/OpenAI SDKs, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands, ASGI apps, and multi-agent SharedContext. The README reports seeded offline proof benchmarks: 21% savings on code search, 57% on SRE incident debugging, 42% on codebase exploration, and 30% on GitHub issue triage, with repeated JSON/log payloads clearing 90%. Compression latency is reported at well under a millisecond at 10K tokens. Accuracy evals in the README show no detectable difference on GSM8K and TruthfulQA, and 97% on SQuAD v2 and BFCL at 19–32% compression. Installation: `uv tool install --python 3.13 "headroom-ai[all]"`, `pip install "headroom-ai[all]"`, `npm install headroom-ai` (TypeScript SDK only, no CLI), or Docker image `ghcr.io/headroomlabs-ai/headroom`. Requires Python 3.10+; licensed under Apache 2.0. Granular extras include `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]`, `[image]`, and framework adapters.