headroom is a local proxy that Claude Code sends its API requests through. It compresses the newest part of each request (fresh tool output, the latest turn) before it reaches the model, and passes everything else through unchanged.
What it is
An open-source (Apache 2.0) project from Headroom Labs, mostly Python with a Rust core. You point Claude Code at it with ANTHROPIC_BASE_URL, the setting that tells Claude Code which API host to call. A router inside detects the content type and picks a compressor: JSON keeps errors, outliers and the first and last items; code is shrunk using its syntax tree (AST); prose goes through a small local model. Compression runs on your machine.
Two design choices matter for Claude Code:
- The cache survives. headroom leaves the earlier part of the conversation byte-identical, so the prompt cache still hits. Only the new “live” part gets compressed.
- Compression is reversible. Originals are kept locally for a while, and the model can call a
headroom_retrievetool to get the full text back when the compressed version is not enough.
What problem it solves
rtk shrinks shell output only, and only for the Bash tool. A lot of what fills a session comes from elsewhere: file reads, MCP results, large JSON responses. Because headroom sits on the wire, it sees every request, whatever produced it.
The project claims about 20% fewer tokens for coding agents and far more for repetitive JSON and logs. Its own savings report warns that some events are priced at list price, so the real saving is likely lower.
How to try it
uv tool install --python 3.13 "headroom-ai[all]"
# one-off: start a proxy and launch Claude Code through it
headroom wrap claude
# or permanent: a background service on 127.0.0.1:8787
headroom install apply --preset persistent-service
headroom install status
headroom savings # tokens saved over the last 30 daysheadroom install apply keeps the proxy running as a service and edits the env block of ~/.claude/settings.json, so every Claude Code session goes through it. For Claude it also sets ENABLE_TOOL_SEARCH=true (see Gotchas). headroom install remove undoes the deployment.
Your subscription keeps working. When only ANTHROPIC_BASE_URL is set, without an API key or gateway token, Claude Code still sends your claude.ai login, so requests count against your plan’s usage limits, not a per-token bill.
Usage example
Frontend
A Next.js session where the agent pulls a large JSON fixture or an API response through an MCP tool to build a component. The response passes through headroom on the next request: it keeps the shape, errors and edge items and drops the repetitive middle. If the agent needs the full payload later, it calls headroom_retrieve.
Backend
A Node service with a noisy log. The agent reads 5,000 lines of a log file with the built-in Read tool, which rtk never sees. headroom compresses that tool result in flight. To see what it actually did to recent requests, run headroom inspect (the proxy has to be started with message logging on).
Who it’s for and when
People who already trimmed the obvious (see Reducing token usage) and still hit limits on long, tool-heavy sessions. It gains little on short chats, prose or output that is already dense.
Gotchas
-
Some Claude Code features switch off behind a proxy. Remote Control stops working, and MCP tool search is off by default. See Custom base URL for the full list. The persistent install sets
ENABLE_TOOL_SEARCH=truefor Claude, which keeps tool search on through the proxy. -
Skip the proxy for one session.
--settingson the command line takes precedence over~/.claude/settings.json, so an empty value turns the proxy off just for that launch, for example to use Remote Control:claude --settings '{"env":{"ANTHROPIC_BASE_URL":""}}' --remote-control -
Telemetry is on by default. An anonymous beacon sends ratios, counters, model IDs and OS details, never prompts, code or file paths. Turn it off with
HEADROOM_TELEMETRY=off(orDO_NOT_TRACK=1). -
One more process on the path. If the proxy is down, Claude Code cannot reach the API until you fix it or unset the URL.