headroomlabs-ai/headroom

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

What it solves

Headroom is a context compression layer designed to reduce the number of tokens sent to and received from LLMs. It targets the high cost and token limits of AI agents by compressing tool outputs, logs, RAG chunks, files, and conversation history, often reducing token usage by 60-95% for JSON and 15-20% for coding agents without sacrificing accuracy.

How it works

Headroom operates as a local-first proxy, library, or MCP server that sits between the AI agent and the LLM provider. It uses a ContentRouter to detect content types and apply specific compressors:

  • SmartCrusher: For JSON data.
  • CodeCompressor: AST-aware compression for multiple programming languages.
  • Kompress-v2-base: A specialized HuggingFace model for prose/text.
  • CacheAligner: Ensures prefixes remain stable to maximize provider KV cache hits.
  • CCR (Reversible Compression): Caches original content locally, allowing the LLM to retrieve the full version via a tool call if needed.

It also reduces output tokens by steering the model toward terseness and adjusting reasoning effort for routine steps.

Who it’s for

  • Developers running AI coding agents (like Claude Code, Cursor, Aider) who want to lower costs and latency.
  • Teams building multi-agent workflows that require shared, deduplicated memory across different LLMs.
  • Developers integrating LLM applications via Python or TypeScript SDKs.

Highlights

  • Multiple Deployment Modes: Available as a drop-in proxy, an inline library, or an MCP server.
  • Agent Wrapping: One-command wrapping for a wide array of agents (e.g., Claude Code, Copilot CLI, Grok).
  • Output Reduction: Trims model preambles and adjusts reasoning effort to save on expensive output tokens.
  • Cross-Agent Memory: Shared context store that works across different providers like Gemini, Grok, and Claude.
  • Failure Mining: The headroom learn command analyzes failed sessions to write corrections to agent configuration files.