headroom-ai

What it is and what it does

Headroom is a context compression layer that sits between your AI agent or application and the LLM provider. It detects content type (JSON, code, prose) and applies specialized compressors to reduce token count before the prompt reaches the model. The package runs locally, keeping your data on-device, and offers multiple integration modes: inline library, HTTP proxy (zero code changes), CLI agent wrapping, or MCP server for any MCP client.

Beyond input compression, the package also trims model output by steering verbosity and routing thinking effort, reducing the tokens you pay for on expensive output-heavy models. Compressed content is reversible via CCR (cached for on-demand retrieval), and the package includes cross-agent memory for deduplication, plus a learn command that mines failed sessions to improve future agent behavior.

Use it for:

• Reduce token costs on long code search results or large log outputs sent to agents by 60–95%.
• Deploy a local proxy in front of an existing agent without changing application code.
• Compress RAG chunks and conversation history in agent pipelines to fit more context in a fixed token budget.
• Share and deduplicate compressed context across multiple AI agents via cross-agent memory.
• Mine failed agent sessions to auto-generate corrections and improve future agent behavior.
• Trim model output verbosity and thinking effort on routine steps to cut output token costs.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Compresses LLM prompts and agent outputs before they reach the model, reducing token usage by 60–95% on structured data while preserving accuracy, via library, proxy, CLI wrapping, or MCP server.

Yes. Actively maintained, well-documented, carries no security vulnerabilities, and offers substantial token savings (60–95% on structured data) with reversible compression and multiple integration modes. The permissive Apache-2.0 license and broad Python version support (3.10–3.14) make it production-ready. Install if you run LLM agents or applications and want to reduce token costs without rewriting code; the proxy mode requires zero changes to existing workflows.

Install

headroom-ai on PyPI

pip install headroom-ai

uv add headroom-ai

poetry add headroom-ai

Installing headroom-ai

Before you install

Medium friction: 10 runtime dependencies including tiktoken, litellm, pydantic, and ast-grep-cli. Actively maintained (last commit 2026-08-14, 66362 stars). Requires Python 3.10+. Wheels available for macOS (x86_64, arm64), Linux (x86_64, aarch64), and Windows.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions—suitable for production deployment in most contexts.

Quickstart

pip install 'headroom-ai[all]'

from headroom import compress

compressed = compress(messages=[{"role": "user", "content": "..."}])

Requires Python 3.10 or later. Some optional extras require a C++ toolchain. The CLI is available only via the PyPI package.

Verify before relying

• Whether the 60–95% token savings on JSON and 15–20% on coding agents hold across different LLM providers and workload types beyond the documented examples.
• Whether reversible compression (CCR) retrieval adds latency or complexity in production agent workflows.
• How cross-agent memory deduplication performs at scale across many concurrent agent sessions.
• Performance characteristics of the ContentRouter and specialized compressors under high-volume or real-time constraints.

Package facts

Evidence: headroom_ai-0.35.0-cp310-abi3-macosx_10_12_x86_64.whl; headroom_ai-0.35.0-cp310-abi3-macosx_11_0_arm64.whl; headroom_ai-0.35.0-cp310-abi3-manylinux_2_28_aarch64.whl; headroom_ai-0.35.0-cp310-abi3-manylinux_2_28_x86_64.whl; headroom_ai-0.35.0-cp310-abi3-win_amd64.whl

Keywords: llm, openai, anthropic, claude, gpt, context, token, optimization, compression, caching, proxy, ai, machine-learning

Tags

More Python Modules packages

Further reading