---
title: "Headroom"
subtitle: "Local context compression for AI agents"
slug: "headroom"
type: "AI-agent tool"
license: "Apache-2.0"
source: "headroomlabs-ai/headroom"
---

# Headroom

## Local context compression for AI agents

**Headroom is an open-source, local-first context-compression tool for AI agents.** It can reduce tool outputs, logs, RAG chunks, files, and conversation history before they reach a model—through a Python or TypeScript library, a local proxy, agent wrappers, or an MCP server.

Compression happens on the machine running Headroom. The project is licensed under [Apache-2.0](https://github.com/headroomlabs-ai/headroom/blob/main/LICENSE).

## What it changes

```text
agent or application
  → tool outputs · logs · RAG results · files · history
  → Headroom (local compression + retrieval)
  → model provider
```

Headroom routes JSON, source code, and prose through different compressors, preserves the original material locally for retrieval, and offers a proxy when changing application code is not the right integration point.

## Start with the CLI

The current upstream quickstart recommends an isolated Python install for the CLI:

```bash
uv tool install --python 3.13 "headroom-ai[all]"
headroom deploy
headroom doctor
```

`pip install "headroom-ai[all]"` also installs the CLI. `npm install headroom-ai` is the TypeScript SDK only; it does **not** install the `headroom` command. Headroom requires Python 3.10+; the upstream install guide has platform, Docker, and persistent-install details.

## Use it with Claude Code or Codex

Headroom’s current compatibility table lists both Claude Code and Codex as supported wrapper targets:

```bash
headroom wrap claude
# or
headroom wrap codex
```

The wrapper starts a local proxy and launches the selected coding agent configured to route through it. Undo a durable wrapper with `headroom unwrap <tool>`. Any OpenAI-compatible client can instead use `headroom proxy`.

## Use it inline in Python

```python
from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=result.messages,
)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
```

Headroom also exposes MCP tools for compression, retrieval, and stats, and it supports TypeScript, proxy, middleware, and framework integrations in the upstream documentation.

## Read the savings and quality claims carefully

The project publishes seeded offline examples built from real MCP-output formats: 21% reported savings for code search, 57% for one SRE-debugging scenario, 42% for codebase exploration, and 30% for issue triage. Those are useful reproducible examples—not a promise for every agent or prompt.

Savings depend on the workload. The README says repetitive JSON arrays and log lines can compress heavily, while prose, short exchanges, and already-dense output may see little or no reduction. Run `headroom savings` or your own controlled evaluation against the traffic you actually care about.

The upstream evaluation table includes a small N=100 comparison on selected benchmarks. It does not establish universally unchanged answer quality. Treat answer quality, retrieval behavior, latency, and token savings as properties to test in your own task and failure modes before relying on them in production.

## Data and operational notes

- Compression is local-first; the project says prompts, completions, code, and file paths are not sent for compression.
- Its README also documents an anonymous telemetry beacon enabled by default for compression ratios, counters, provider/model IDs, OS, and architecture. It can be disabled with `HEADROOM_BEACON=off`, `DO_NOT_TRACK=1`, or `--offline`.
- Headroom is most relevant to long agent sessions with substantial tool output. It is less compelling when a local process cannot run or a single provider’s native compaction already covers the needed case.

## Links and evidence

- [Start with Headroom’s quickstart](https://docs.headroomlabs.ai/docs/quickstart)
- [View the open-source repository](https://github.com/headroomlabs-ai/headroom)
- [Read the current README](https://github.com/headroomlabs-ai/headroom#readme)
- [Installation guide](https://docs.headroomlabs.ai/docs/installation)
- [Benchmark methodology](https://docs.headroomlabs.ai/docs/benchmarks)
- [Known limitations](https://docs.headroomlabs.ai/docs/limitations)
- [Telemetry and proxy documentation](https://docs.headroomlabs.ai/docs/proxy)