TL;DR
Headroom is an open-source tool that compresses all context read by AI agents before passing it to the LLM, dramatically reducing token costs.
Key features
Library: Inline compression via compress(messages) in Python/TypeScript
Proxy: headroom proxy --port 8787 for use in any language without code changes
Agent wrapper: One-line command headroom wrap claude|codex|cursor|aider|copilot to integrate with major AI agents
MCP server: Provides headroom_compress, headroom_retrieve, headroom_stats tools
Cross-agent memory: Shared storage across Claude, Codex, Gemini with automatic deduplication
headroom learn: Analyzes failed sessions and records fixes in CLAUDE.md/AGENTS.md
Decompression (CCR): Original content is not deleted; LLM can retrieve it when needed
When to use it
To save context window and reduce costs for AI agents (Claude Code, Cursor, Codex, etc.)
To compress retrieved chunks in RAG systems and lower LLM call costs
Any situation where large amounts of text (logs, tool outputs, files) need to be passed to an LLM
To transparently add a compression layer to existing agent workflows without code changes