DEVOURED
Headroom (GitHub Repo)
Headroom compresses AI agent context by 60-95% with zero code changes, reversible local storage, and 60B+ tokens saved across the community.
What: Headroom is an Apache 2.0 tool that compresses everything AI agents read—tool outputs, logs, RAG chunks, files—before reaching the LLM, achieving 60-95% token reduction. Real benchmarks: 17,765→1,408 tokens (92%) for code search, 65,694→5,118 (92%) for SRE debugging. Accuracy preserved on GSM8K, TruthfulQA, SQuAD v2. Works as Python/TypeScript library, drop-in proxy (headroom proxy), MCP server, or agent wrapper (headroom wrap claude/codex/cursor). Uses SmartCrusher (JSON), CodeCompressor (AST), and Kompress-base (HuggingFace model). Reversible via CCR—originals stored locally, LLM retrieves on demand.
Why it matters: Token costs are becoming a real bottleneck for AI agent adoption—enough that developers are building open-source, local-first compression instead of waiting for providers. The cross-agent memory feature signals agents evolving from isolated sessions to persistent, shared context across tools.
Takeaway: Install with `pip install "headroom-ai[all]"` and run `headroom wrap claude` for Claude Code, or `headroom proxy --port 8787` for zero-code integration with any OpenAI-compatible client.
Deep dive
- Compression pipeline: CacheAligner stabilizes prefixes for provider KV cache hits, ContentRouter selects algorithm by content type, SmartCrusher handles JSON/nested objects, CodeCompressor handles AST (Python/JS/Go/Rust/Java/C++), Kompress-base (HuggingFace model) handles text
- CCR reversible compression: originals stored locally, LLM calls headroom_retrieve when needed, solves "compression loses critical detail" problem
- Cross-agent memory: shared context store across Claude, Codex, Gemini with auto-dedup and provenance tracking
- Integration modes: library (compress(messages)), SDK wrapper (withHeadroom(new Anthropic())), drop-in proxy (zero code changes), MCP server, agent wrapper (headroom wrap claude|codex|cursor|aider)
- Benchmarks: 92% reduction on code search and SRE debugging, 73% on GitHub triage, 47% on codebase exploration; accuracy preserved on GSM8K (0.870→0.870), TruthfulQA (0.530→0.560), SQuAD v2 (97% with 19% compression)
- headroom learn: mines failed sessions, auto-writes corrections to CLAUDE.md/AGENTS.md/GEMINI.md
- Compatible with Claude Code, Codex, Cursor, Aider, Copilot CLI, LangChain, Agno, Strands, Vercel AI SDK, any OpenAI-compatible client
- Requirements: Python 3.10+, runs locally (data stays on your machine)
- Community: 60B+ tokens saved (live leaderboard), Apache 2.0 license
Decoder
- CCR: Headroom's reversible compression mode where originals are stored locally and retrieved on-demand via the headroom_retrieve tool when the LLM needs them.
- MCP (Model Context Protocol): Standardized protocol for AI tools to expose context and capabilities to LLM clients like Claude or Copilot.
Original article
Full article content is not available for inline reading.
Explore all 67 articles in today's digest
Fresh dev news, AI-digested daily. Never miss a trend at devoured.fyi