Overview
Headroom compresses everything an AI agent reads — tool outputs, logs, RAG chunks, files and conversation history — before it reaches the model. The goal is the same answer from far fewer tokens. The project reports 60–95% fewer tokens on JSON data and 15–20% fewer for coding agents, and its demo shows a 10,144-token input reduced to 1,260 while still surfacing the same FATAL log line.
It runs locally, so the data being compressed stays on your machine, and it exposes four entry points for different integration styles: a library (`compress(messages)` in Python or TypeScript), a drop-in proxy that needs no code changes in any language, a one-command wrapper around a specific coding agent, and an MCP server exposing `headroom_compress`, `headroom_retrieve` and `headroom_stats` to any MCP client.
Internally a ContentRouter detects the content type and picks a matching compressor: SmartCrusher for JSON, CodeCompressor for AST-aware code, and the Kompress-v2-base model for prose. A CacheAligner detects and warns about volatile content that would bust a provider's KV-cache prefix, without rewriting prompts itself. Compression is reversible — originals are cached locally under a scheme the project calls CCR, and the model can call `headroom_retrieve` when it needs the untruncated version. Headroom also ships cross-agent memory shared across agents with automatic dedup, and a `headroom learn` command that mines failed sessions and writes corrections into `CLAUDE.local.md`, `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` or `GROK.md`.
What it does
- Content-aware compressors — SmartCrusher for JSON, CodeCompressor for AST, Kompress-v2-base for prose — selected automatically by a ContentRouter
- Four integration modes: Python/TypeScript library, drop-in proxy, one-command agent wrap, and MCP server
- Reversible compression (CCR): originals cached locally and retrievable by the model on demand
- CacheAligner warns about volatile content that would invalidate a provider's KV-cache prefix, without rewriting prompts
- Cross-agent memory shared across Claude, Codex, Gemini and Grok with automatic dedup
- Output token reduction that trims what the model writes back, not only what you send
Getting started
Install the CLI, choose an integration mode, then verify the savings. Note that the npm package ships the TypeScript SDK only — the `headroom` CLI comes from the uv or pip install.
Install
Use uv or pip for the CLI; npm gives you the TypeScript SDK without the CLI.
uv tool install --python 3.13 "headroom-ai[all]" # CLI as a global tool
pip install "headroom-ai[all]" # Python — ships the `headroom` CLI
npm install headroom-ai # TypeScript SDK onlyPick a mode
Wrapping a coding agent starts a local proxy, installs Serena for semantic code navigation, and launches the agent configured to route through Headroom. Undo it with `headroom unwrap <tool>`, or skip Serena with `--code-memory none`.
headroom deploy # turnkey local deployment + agent config
headroom wrap claude # wrap a coding agent
headroom proxy --port 8787 # drop-in proxy, zero code changes
# or inline: from headroom import compressVerify the setup and watch the savings
`doctor` confirms routing is working; the dashboard needs the proxy running.
headroom doctor
headroom perf
headroom dashboard
Commands and code are distilled from the project's own documentation — always check the official repo for the latest.
When to use it
- Cut the token bill of a coding agent that keeps reading long logs, test output and large files
- Compress verbose JSON tool responses before they reach the model, where the reported savings are largest
- Add compression to an existing app with no code change by pointing it at the local proxy
- Keep compression reversible so an agent can pull the original text back when a summary is not enough
How Headroom compares
Headroom alongside other open-source context compression & token budgets tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| RTK | ★ 84.3k | A single-binary Rust CLI proxy that filters, groups, truncates and dedupes the output of 100+ dev commands before a coding agent reads it, cutting token use by 60–90%. |
| Headroom | ★ 77.6k | The context compression layer for AI agents |
| Context Mode | ★ 31.8k | An MCP server that keeps raw tool output out of the context window by sandboxing it, and indexes session events into SQLite FTS5 so an agent survives compaction. |
| TOON | ★ 25.5k | Token-Oriented Object Notation: a lossless, compact encoding of the JSON data model that declares row counts and field lists so tabular data costs fewer prompt tokens. |
| pxpipe | ★ 7.5k | A local proxy that renders bulky request context — system prompt, tool docs and older turns — as PNG pages the model reads with vision, cutting the input tokens a coding agent re-sends each turn. |
| LeanCTX | ★ 3.9k | Local context layer for coding agents with ten file read modes, 95+ shell-output compressors, reversible content-addressed recovery, session memory and a savings ledger. |
| CliffCompaction | ★ 65 | A transparent API proxy that trims a coding agent's history at a token threshold by truncating and dropping content only, never rewriting it, so summaries never stack on summaries. |