# Headroom review

> Headroom compresses tool outputs, logs, files, and RAG chunks locally before they reach the LLM, as a library, proxy, or MCP server.

Devtoolwatch Board, the week of Oct 25–31, 2026. Canonical page: https://index.devtoolwatch.com/tools/headroomlabs-ai-headroom/

## TL;DR

Headroom is a context compression layer that shrinks what AI agents read before it reaches the model, and can also trim model output. It is for developers running coding agents or LLM apps who want fewer tokens. It runs locally, keeps originals for retrieval on demand, and wraps many coding agents in one command.

## Headroom at a glance

- **Category:** [Model SDKs and gateways](https://index.devtoolwatch.com/categories/model-sdks-and-gateways/)
- **Maintained by:** Headroom Labs (organization, [@headroomlabs-ai](https://github.com/headroomlabs-ai) on GitHub)
- **License:** Apache 2.0
- **Language:** Python, Rust, TypeScript
- **Repository:** [github.com/headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom)
- **Website:** [docs.headroomlabs.ai/docs](https://docs.headroomlabs.ai/docs)
- **PyPI package:** [headroom-ai](https://pypi.org/project/headroom-ai/) 0.41.0
- **Latest release:** [v0.41.0](https://github.com/headroomlabs-ai/headroom/releases/tag/v0.41.0) on GitHub, Oct 14, 2026
- **First published:** Jan 7, 2026

## What Headroom does

- Headroom compresses messages inline with compress(messages) in Python or TypeScript.
- Headroom runs as a local proxy that needs no code changes and works with any OpenAI-compatible client.
- Headroom wraps coding agents such as Claude Code, Codex, Aider, and Cline in one command, undone with headroom unwrap.
- Headroom routes content by type to compressors for JSON, source code via AST, and prose via the Kompress-v2-base model.
- Headroom caches originals locally (CCR) so the model can call headroom_retrieve for the full text.
- Headroom can trim model output through verbosity steering and effort routing in the proxy, off by default.
- Headroom offers cross-agent memory and headroom learn, which writes corrections from failed sessions to files like CLAUDE.local.md.

### How it works

Headroom sits between your agent or app and the LLM provider, such as Anthropic, OpenAI, or Bedrock. You use it as a Python library, TypeScript SDK, local proxy, agent wrapper, or MCP server. A ContentRouter picks a compressor per content type. CacheAligner flags content that would break provider prompt caching. Compression runs on your machine.

## How to install Headroom

**With uv (CLI)**

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

**With pip**

```
pip install "headroom-ai[all]"
```

**With npm (TypeScript SDK only)**

```
npm install headroom-ai
```

### Requirements

- Python 3.10 or later for the PyPI package.
- An API key or account with your LLM provider, such as Anthropic or OpenAI.

### First steps

1. Run headroom deploy for a turnkey local deployment and agent configuration.
2. Or run headroom wrap claude to route a coding agent through Headroom.
3. Run headroom doctor to confirm routing works.
4. Run headroom dashboard to watch live savings while the proxy is running.

## Who Headroom is for

- Developers using coding agents like Claude Code, Codex, or Aider who want to cut input tokens.
- Apps sending large repetitive JSON tool outputs or logs to an LLM.
- Teams that want compression to run locally without sending prompts elsewhere.

### Limitations

- Headroom saves little on prose and already-dense output; savings scale with how repetitive the payload is.
- Headroom supports Cursor only through manual setup and Cortex Code only in library mode.
- Headroom output savings are reported as estimates unless you hold out conversations as a control.
- Headroom source code compression is opt-in and disabled by default.

## Usage data (the week of Oct 25–31, 2026)

- Board rank: #77 overall, #2 in Model SDKs and gateways, momentum score 68
- Downloads that week: 125.8k (+22% vs 4-week average)
- New GitHub stars per week (last 12 weeks): Aug 9: 988; Aug 16: 840; Aug 23: 890; Aug 30: 1.1k; Sep 6: 2.8k; Sep 13: 1.4k; Sep 20: 842; Sep 27: 550; Oct 4: 699; Oct 11: 719; Oct 18: 2.2k; Oct 25: 798

## Headroom alternatives

| Rank | Tool | Stars | Downloads/wk |
|---|---|---|---|
| #1 | [thinking-orbs](https://index.devtoolwatch.com/tools/jakubantalik-thinking-orbs/) | 3.9k | 1.4M |
| #3 | [LiteLLM](https://index.devtoolwatch.com/tools/litellm/) | 62.5k | 23.1M |
| #4 | [Honcho](https://index.devtoolwatch.com/tools/plastic-labs-honcho/) | 7.9k | – |
| #5 | [Anthropic SDK](https://index.devtoolwatch.com/tools/anthropic-sdk/) | 4k | 111M |
| #6 | [Hugging Face Hub](https://index.devtoolwatch.com/tools/hf-hub/) | 4k | 68.3M |
| #7 | [OpenAI SDK](https://index.devtoolwatch.com/tools/openai-sdk/) | 32k | 141.3M |

## Headroom FAQ

### Is Headroom free and open source?

Yes. Headroom's source code is on GitHub (headroomlabs-ai/headroom) under the Apache 2.0 license, so you can use it for free.

### How do I install Headroom?

Run `uv tool install --python 3.13 "headroom-ai[all]"`. The headroom-ai package needs Python 3.10 or newer. The install section above has the other options from the project's README.

### Is Headroom still maintained?

Yes. The headroomlabs-ai/headroom repository was last updated on Oct 22, 2026, and the latest release, v0.41.0 on GitHub, came out on Oct 14, 2026.

### How popular is Headroom?

Headroom has 78.5k GitHub stars as of Nov 1, 2026. It gained 798 new stars in the week of Oct 25–31, 2026, against a 12-week average of 1.1k a week. Its main package had 125.8k downloads that week, +22% against its own 4-week average. That made it #2 among LLM SDKs and gateways on the Devtoolwatch Board.

### Headroom vs RTK: how do they compare?

Headroom and RTK are both tracked by Devtoolwatch. Headroom has 78.5k GitHub stars and RTK has 85.1k. [RTK review](https://index.devtoolwatch.com/tools/rtk-ai-rtk/)

### Headroom vs Graphify: how do they compare?

Headroom and Graphify are both tracked by Devtoolwatch. Headroom has 78.5k GitHub stars and Graphify has 140k. In the week of Oct 25–31, 2026, Headroom's main package had 125.8k downloads and Graphify's had 480.7k. Graphify is an AI coding assistant skill that turns a codebase, with its docs, PDFs, images and videos, into a queryable knowledge graph. [Graphify review](https://index.devtoolwatch.com/tools/graphify-labs-graphify/)

### What are the best alternatives to Headroom?

Other LLM SDKs and gateways on the Devtoolwatch Board in the week of Oct 25–31, 2026, by momentum: thinking-orbs (#1), LiteLLM (#3), Honcho (#4), Anthropic SDK (#5), Hugging Face Hub (#6). The alternatives table above has their numbers.

### How do I use Headroom with Claude Code?

Headroom wraps Claude Code with headroom wrap claude. This starts a local proxy, installs Serena for code navigation, and launches Claude Code routed through Headroom. For the VS Code extension, run headroom wrap vscode-claude from your project after installing the proxy extra.

### Is Headroom safe for my code and prompts?

Headroom runs compression on your machine. The README states no prompt or file content is sent anywhere to be compressed, and originals are cached locally.

### How do I use Headroom with GitHub Copilot?

Headroom supports Copilot CLI and VS Code Copilot. Run headroom copilot-auth login, then headroom wrap copilot --subscription or headroom wrap vscode. VS Code keeps your selected model.

### How do I use Headroom with Cursor?

Headroom needs manual setup for Cursor. It starts the proxy and prints base URLs to enter in Cursor settings.

### How do I use Headroom with OpenCode?

Headroom wraps OpenCode with headroom wrap opencode, which injects config and starts the proxy. For third-party providers like DeepSeek, pass --openai-api-url. Version 0.41.0 added support for the OpenCode 2.x plugin API.

### Does Headroom change model answers?

Headroom's published tier 1 evals show no detectable accuracy difference on GSM8K and TruthfulQA at N=100. Run python -m headroom.evals suite --tier 1 to reproduce.

## Sources

1. [headroomlabs-ai/headroom on GitHub](https://github.com/headroomlabs-ai/headroom)
2. [Headroom README](https://github.com/headroomlabs-ai/headroom/blob/main/README.md)
3. [headroom-ai on PyPI](https://pypi.org/project/headroom-ai/)
4. [Headroom website](https://docs.headroomlabs.ai/docs)
5. [Release v0.41.0 (Oct 14, 2026)](https://github.com/headroomlabs-ai/headroom/releases/tag/v0.41.0)
6. [Release v0.40.0 (Oct 6, 2026)](https://github.com/headroomlabs-ai/headroom/releases/tag/v0.40.0)
7. [Release v0.39.1 (Sep 26, 2026)](https://github.com/headroomlabs-ai/headroom/releases/tag/v0.39.1)
8. [Hacker News: Headroom - compress AI agent input for reduced token usage w/out harming output](https://news.ycombinator.com/item?id=48999841)
9. [Devtoolwatch Board, the week of Oct 25–31, 2026](https://index.devtoolwatch.com/)