Headroom

Overview

Headroom is a context optimization layer for LLM applications. It compresses tool outputs, database results, file reads, RAG retrievals, API responses, logs, and conversation history before they reach the model, so the model sees less noise. Compression runs locally, and compressed content is reversible through a local CCR store.

Key Features

• Reversible compression (CCR) stores originals locally and gives the model a headroom_retrieve tool for full details.
• Smart content detection routes JSON, source code, logs, text, diffs, and HTML to the best compressor with zero configuration.
• SmartCrusher preserves errors, anomalies, and first and last boundaries in JSON tool outputs through statistical analysis.
• Works as a transparent proxy, Python or TypeScript library, agent wrapper, or MCP server.
• Cache optimization stabilizes prefixes to help provider KV caches hit and tracks frozen messages to preserve cache read discounts.
• Persistent memory uses hierarchical user, session, agent, and turn scopes with SQLite and HNSW backends.

Use Cases

• Reduce tokens from tool outputs, logs, database reads, RAG results, file reads, and API responses before sending them to an LLM.
• Preserve critical errors during SRE incident debugging while compressing large, mostly routine tool output.
• Compress context during codebase exploration and GitHub issue triage.
• Share compressed context between agents across frameworks with SharedContext.

Getting Started

• Install the Python package with uv tool install --python 3.13 "headroom-ai[all]" or pip install "headroom-ai[all]"; install the TypeScript SDK with npm install headroom-ai.
• Choose a mode: headroom deploy for turnkey local deployment, headroom wrap claude to wrap a coding agent, headroom proxy --port 8787 for a drop-in proxy, or use the inline Python library.
• Run headroom doctor to confirm routing works, then headroom perf or headroom dashboard to view savings.

Deployment & Requirements

• Compression runs locally on your machine; no prompt or file content is sent anywhere to be compressed.
• The headroom CLI ships only in the PyPI package; the npm headroom-ai package is the TypeScript SDK and provides no headroom command.
• Docker-native installation is documented as an install option.
• A local proxy can be run on port 8787.

Before You Adopt

• License: Apache-2.0. Review its terms before using, modifying, or distributing the project.
• Compression savings depend on how repetitive the input is, so benchmark figures should be treated as workload-specific.
• Source code compression is optional and off by default.
• Prose and already-dense outputs may compress very little.