Skip to content
ML2
Small Tools, Repos & PluginsTool#Local / BYO model#MCP#Open source#CLI

Headroom: compress what your coding agent reads

Added NewCopyable prompt below

Published Last verified Released

Our verdict

A practical fix when agent sessions burn tokens on long logs, search results and JSON: wrap Claude Code or Codex with one command, or put the proxy in front of any OpenAI-compatible client, and repetitive payloads shrink before they hit the model. Compression runs locally, and the model can call headroom_retrieve for the original when it needs it. Savings depend on how repetitive your traffic is (the project's own benchmarks range from 21% on code search to over 90% on repeated JSON and logs), so run headroom savings on your own work. An anonymous usage beacon is on by default; turn it off with HEADROOM_TELEMETRY=off.

Who it's for
Heavy Claude Code, Codex or Cursor users, and developers building agents with large tool outputs
Leverage
Lower token bills and more room in the context window, without changing your agent
Effort
Medium
Date added

What it does

Headroom (headroomlabs-ai/headroom, Apache-2.0) sits between your agent and the model. It ships as a Python library and CLI (pip install "headroom-ai[all]"), a TypeScript SDK (npm headroom-ai, no CLI), a drop-in proxy (headroom proxy --port 8787) and an MCP server with headroom_compress, headroom_retrieve and headroom_stats. headroom wrap configures and launches Claude Code, Codex, Copilot, Cursor, Aider, OpenCode, Goose and others to route through the local proxy, and also installs Serena for code navigation (skip it with --code-memory none); headroom unwrap undoes it. CCR keeps originals cached locally so compression is reversible. Extras include cross-agent memory, headroom learn (writes corrections from failed sessions to CLAUDE.local.md or AGENTS.md) and a live savings dashboard.

How builders use it

  • Install the CLI in its own environment: uv tool install --python 3.13 "headroom-ai[all]".
  • Run headroom wrap claude (or codex, cursor, opencode) to start a session through the local proxy, and headroom doctor to confirm routing.
  • For your own app, call compress(messages) before the LLM request, or point any OpenAI-compatible client at headroom proxy.
  • Check headroom savings or headroom dashboard after a few sessions to see what it saves on your traffic, and set HEADROOM_TELEMETRY=off if you don't want the beacon.

What to expect

The same agent work on fewer input tokens, with the full text one tool call away.

Copy this: Install + wrap

# Official source: github.com/headroomlabs-ai/headroom (Apache-2.0)
uv tool install --python 3.13 "headroom-ai[all]"
# or: pip install "headroom-ai[all]"

# Optional: turn off the anonymous beacon
export HEADROOM_TELEMETRY=off

# Wrap a coding agent (undo: headroom unwrap claude)
headroom wrap claude
headroom doctor

# Or a drop-in proxy for any OpenAI-compatible client
headroom proxy --port 8787

# MCP clients
headroom mcp install

# See what it saved on your traffic
headroom savings

Related discoveries

See the newest picks →

Want more like this?

Practical discoveries, without the noise.

Get the newsletterMore in Small Tools, Repos & Plugins