# headroom

> Shrinks tool outputs, logs, and files before your AI agent sends them to the model

- Repository: https://github.com/headroomlabs-ai/headroom
- Category: Token & cost savings
- Stars: 77,577 · Forks: 6,020 · Language: Python · License: Apache-2.0
- Experience: Some experience
- Page: https://ir.adyog.com/repos/headroomlabs-ai/headroom/

Coding agents and LLM apps send a lot of bulky text to the model: search results, log dumps, JSON from tools. You pay for every token, and long context crowds out useful information. Headroom sits between your agent and the model provider and shrinks that text first.

It runs locally. A router detects the content type and picks a compressor: one for JSON, one for source code (using the syntax tree), and a small Hugging Face model for plain text. Originals are cached locally, so the model can ask for the full text through a retrieve tool when it needs it.

You can call compress() in Python or TypeScript, run a proxy that any OpenAI-compatible client can point at, or use 'headroom wrap' to launch a supported agent already routed through it. The README's benchmarks show 21% to 57% savings on four agent scenarios. It also says savings depend on how repetitive the data is, and that prose compresses very little.

## What it does

- **Three ways to plug in**: Use it as a Python or TypeScript library, as a proxy with no code changes, or as an MCP server with compress, retrieve and stats tools.
- **One-command agent wrapping**: 'headroom wrap' supports Claude Code, Codex, Aider, Cline, Goose, OpenHands and others. 'headroom unwrap' undoes it. Cursor needs manual setup.
- **Content-aware compression**: A router sends JSON, code and text to different compressors. Originals are stored locally and can be retrieved on demand.
- **Output token reduction**: The proxy can ask the model to be terse and lower thinking effort on routine turns. This is off by default and the savings are reported as estimates.
- **Cross-agent memory and learn**: A shared memory store works across Claude, Codex, Gemini and Grok. 'headroom learn' reads failed sessions and writes corrections to files like CLAUDE.md or AGENTS.md.

## What you could build

- Cut the token cost of a Claude Code or Codex session by wrapping it with headroom.
- Compress large JSON or log output from tools before sending it to GPT-4o in your own app.
- Put a local proxy in front of an OpenAI-compatible client to shrink every request without code changes.
- Shrink RAG chunks before they go into the prompt of a LangChain pipeline.
- Measure how many tokens your own agent traffic saves using the savings and dashboard commands.

## Who it's for

Developers who run coding agents or LLM apps and want lower token bills; you should know how to use a CLI and, for the library, basic Python.

## Get started

Install the Python package, which includes the headroom CLI. Then wrap a coding agent with 'headroom wrap', or start the proxy and point your client at it. Run 'headroom doctor' to check it works and 'headroom perf' to see savings.

```
pip install "headroom-ai[all]"
```
```
headroom wrap claude
```
```
headroom proxy --port 8787
```

Tags: token-optimization, context-compression, proxy, mcp, coding-agents