Headroom review

Q: 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.

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

Updated Nov 1, 2026. Review written Oct 22, 2026 from the project's own sources; usage data refreshed every Monday.

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.

78.5kGitHub stars
+798new stars, week of Oct 25
125.8kdownloads a week, +22% vs 4-week avg
#2in Model SDKs and gateways this week

Headroom at a glance

Category: Model SDKs and gateways
Maintained by: Headroom Labs (organization, @headroomlabs-ai on GitHub)
License: Apache 2.0
Language: Python, Rust, TypeScript
Repository: github.com/headroomlabs-ai/headroom
Website: docs.headroomlabs.ai/docs
PyPI package: headroom-ai 0.41.0
Latest release: 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 and start using 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

Run headroom deploy for a turnkey local deployment and agent configuration.
Or run headroom wrap claude to route a coding agent through Headroom.
Run headroom doctor to confirm routing works.
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 to know

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.

Is Headroom growing? Usage data

In the week of Oct 25–31, 2026, Headroom ranked #77 on the Devtoolwatch Board and #2 in Model SDKs and gateways, with a momentum score of 68 out of 100. Its main package had 125.8k downloads that week, +22% against its own 4-week average.

New GitHub stars per week for the last 12 weeks, from GitHub's stargazer history (today's stargazers by the week they starred).

Show the weekly numbers

New GitHub stars per week for Headroom
Week of	New stars
Aug 9, 2026	988
Aug 16, 2026	840
Aug 23, 2026	890
Aug 30, 2026	1.1k
Sep 6, 2026	2.8k
Sep 13, 2026	1.4k
Sep 20, 2026	842
Sep 27, 2026	550
Oct 4, 2026	699
Oct 11, 2026	719
Oct 18, 2026	2.2k
Oct 25, 2026	798

On Hacker News

Headroom - compress AI agent input for reduced token usage w/out harming output, 10 points and 2 comments (Jul 21, 2026)

The Board ranks tools by four signals each week: new stars, new stars for the repo's size, added downloads and download growth beyond the market. How the ranking works.

Headroom alternatives

Other LLM SDKs and gateways on the Board in the week of Oct 25–31, 2026, by momentum:

Model SDKs and gateways ranked by momentum, the week of Oct 25–31, 2026
Rank	Tool	Stars	Downloads/wk
#1	thinking-orbsthinking-orbs is a React library of dotted, animated thought-orb loading indicators for AI and agent user interfaces.	3.9k	1.4M
#3	LiteLLMLiteLLM is an open source AI gateway and Python SDK that calls 100+ LLM providers through one OpenAI-format interface.	62.5k	23.1M
#4	Honcho Memory library for building stateful agents	7.9k	–
#5	Anthropic SDKAnthropic SDK is the official Python library for calling the Claude API from Python applications.	4k	111M
#6	Hugging Face HubHugging Face Hub is the official CLI and Python client for downloading, uploading and managing models, datasets and Spaces on the…	4k	68.3M
#7	OpenAI SDKOpenAI SDK is the official Python library for the OpenAI API, with typed sync and async clients generated from OpenAI's OpenAPI…	32k	141.3M

All LLM SDKs and gateways, ranked

Recent Headroom releases

v0.41.0, Oct 14, 2026
v0.40.0, Oct 6, 2026
v0.39.1, Sep 26, 2026
v0.39.0, Sep 25, 2026
v0.38.0, Sep 21, 2026

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.

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.

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

Headroom README badge

Maintainers can show the tool's weekly Board rank in their README:

[![Devtoolwatch](https://index.devtoolwatch.com/badge/headroomlabs-ai-headroom.svg)](https://index.devtoolwatch.com/tools/headroomlabs-ai-headroom/)

How this page is made: Devtoolwatch writes each review from the project's README, releases, package metadata and website, with an AI model, then checks every claim against the source it cites and drops what the sources don't support. The numbers come from Devtoolwatch's daily GitHub snapshots, GitHub's stargazer history, and the npm and PyPI download APIs. Spotted an error? Email [email protected].