headroomlabs-ai/headroom

What it solves

Headroom reduces the number of tokens sent to and received from Large Language Models (LLMs), lowering costs and reducing latency for AI agents. It specifically targets the "ceremony" and repetitive data found in tool outputs, logs, RAG chunks, and conversation history that often bloat agent prompts.

How it works

Headroom acts as a local compression layer that sits between the AI agent and the LLM provider. It uses a ContentRouter to detect the type of data and apply the appropriate compression method:

• SmartCrusher: Handles JSON data using statistical variance to keep critical information while removing redundancy.
• CodeCompressor: Uses Abstract Syntax Tree (AST) awareness to compress source code for multiple languages.
• CodeCompressor: Uses a specialized HuggingFace model (Kompress-v2-base) trained on agentic traces for prose.
• CCR (Reversible Compression): Stores original content locally, allowing the model to retrieve the full text via a tool call if needed.
• CacheAligner: Ensures that volatile content does not break the provider's KV-cache prefix, preserving cache hits.

It can be deployed as a library (Python/TypeScript), a drop-in proxy requiring no code changes, or as a wrapper for popular agents like Claude Code, Cursor, and Aider.

Who it’s for

Developers and power users who run coding agents daily, those working across multiple different AI agents who want a shared memory store, and anyone looking to reduce LLM API costs without sacrificing accuracy.

Highlights

• Multi-modal Compression: Specialized compressors for JSON, code, and text.
• Agent Wrapping: One-command setup (headroom wrap) for a wide array of AI agents and IDE extensions.
• Output Token Reduction: Trims model responses by steering verbosity and adjusting reasoning effort for routine tasks.
• Cross-Agent Memory: A shared, deduplicated store for context across different LLM providers.
• headroom learn: Analyzes failed sessions to automatically write corrections to agent configuration files.
• Local Execution: All compression happens on the user's machine; no data is sent to external servers for compression.