Overview

Headroom is a powerful context compression layer designed to significantly reduce the token count for AI agents and LLMs. By intelligently compressing tool outputs, logs, RAG chunks, and conversation history, Headroom enables agents to process more information with fewer tokens, leading to substantial cost savings and improved efficiency without sacrificing answer accuracy. It operates locally on your machine, ensuring your data privacy and security.

Key Features

• Versatile Compression: Utilizes specialized compressors (SmartCrusher for JSON, CodeCompressor for AST, and the Kompress-v2-base model for prose) tailored to different data types.
• Multiple Integration Modes:
  • Library: Easily integrate compress(messages) into your Python or TypeScript applications.
  • Proxy: A drop-in solution requiring zero code changes to compress traffic from any language.
  • Agent Wrappers: Seamlessly wrap popular coding agents like Claude, Codex, Copilot, and more with a single command.
  • MCP Server: Provides headroom_compress, headroom_retrieve, and headroom_stats for MCP clients.
• Reversible Compression (CCR): Original content is cached locally and can be retrieved on demand, ensuring data recoverability.
• Cross-Agent Memory: Facilitates a shared memory store across multiple agents (e.g., Claude, Codex, Gemini, Grok) with automatic deduplication.
• Output Token Reduction: Trims unnecessary verbosity and repetition from LLM responses, further reducing token consumption.
• Intelligent Learning: headroom learn mines failed sessions to identify and apply terseness corrections automatically.
• High Performance: Compression operations are extremely fast, typically under a millisecond, ensuring no noticeable impact on agent latency.
• Privacy-Focused: All compression processes run locally; no prompt or file content is sent externally.

Typical Use Cases

Headroom is ideal for developers and teams working extensively with AI agents, especially in the following scenarios:

• Cost Optimization: Significantly reduce LLM API costs by sending fewer tokens, particularly beneficial for agents that handle large amounts of data or frequent tool interactions. Achieve up to 20% fewer tokens for coding agents and 60-95% for JSON.
• Enhanced Agent Performance: Enable agents to process larger contexts and more detailed information within token limits, potentially leading to more comprehensive and accurate responses.
• Streamlined Development Workflows: Integrate seamlessly with popular coding agents and development tools (VS Code, Cursor, Aider, etc.) without code modifications using the proxy or wrapper modes.
• Data-Intensive Applications: Compress and manage large logs, extensive search results, RAG outputs, and complex codebases efficiently.
• Cross-Agent Collaboration: Leverage shared memory for smoother interaction and context transfer between different AI agents.
• Ensuring Data Integrity: The reversible nature of compression means original data is always accessible, crucial for debugging and auditing.