headroomlabs-ai/headroom

What it does

Headroom sits between an AI agent and the model provider and compresses the material an agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it is sent. It ships as a Python/TypeScript library, a local proxy, an agent wrapper, and an MCP server, so it can be used both by applications that build prompts in code and by coding agents you do not control.

Compression is routed by content type: SmartCrusher handles JSON, CodeCompressor is AST-aware for several languages, and Kompress-v2-base handles prose. Originals are cached locally through CCR and can be retrieved on demand, which makes the compression reversible. Volatile content is flagged so provider KV-cache prefixes are not invalidated.

Quick start

For an application that builds its own prompt, install the package and compress the message list before the provider call:

pip install headroom-ai

from headroom import compress

result = compress(messages, model="gpt-4o")
client.chat.completions.create(model="gpt-4o", messages=result.messages)

For a coding agent, install the full CLI set and wrap the agent. This starts a local proxy configured for that tool and is session-scoped:

uv tool install --python 3.13 "headroom-ai[all]"
headroom wrap claude

After either setup, headroom doctor confirms routing and headroom dashboard shows live savings while the proxy runs. Compare your own traffic with headroom savings; the README's benchmark table is seeded and offline, so it reproduces the project's numbers rather than your workload. The quickstart covers the TypeScript SDK, proxy, and MCP paths.

Constraints

• Requires Python 3.11+. The CLI is shipped only in the PyPI package; the npm package is the TypeScript library and exposes no headroom command.
• Native wheels cover macOS Apple Silicon and Linux. Intel macOS needs the Docker install or a system ONNX Runtime workaround (issue #941); x86 hosts without AVX2 fall back to non-ONNX paths.
• [all] does not include framework adapters; install [langchain], [agno], [strands], and similar separately. Torch-backed features are separate extras.
• Savings depend on content: repeated JSON arrays and logs compress most, prose and already-dense output little, and short prompts may come back byte-identical.
• An anonymous telemetry beacon is on by default and can be disabled with HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off, DO_NOT_TRACK=1, or HEADROOM_OFFLINE=1.
• Output-token shaping is off by default and reports an estimate unless a holdout is configured.
• For third-party OpenAI-compatible providers, pass --openai-api-url or set OPENAI_TARGET_API_URL; otherwise requests go to the default OpenAI endpoint.

HotRepo's take

The project reached 76,073 stars on the all-language daily list on 2026-10-19, gained 317 stars that day, and stood at 79,529 stars with 6,226 forks when it appeared at 8th on the Python daily list on 2026-11-13. That is a sharp rise for a context-compression utility, and the debate around the category is visible on Hacker News: one commenter asks why providers have not shipped equivalent savings by default and questions headline benchmarks (discussion), while a reply notes that whitespace removal in JSON likely does account for real token reductions (reply). The repository answers part of that challenge with a shipped proof script, accuracy evals, and a reversible cache, but the numbers are per-workload, so the decisive test is headroom savings on your own traffic rather than the table.