FAQ
Headroom FAQ for Claude Code and ChatGPT cost savings
These are the questions people usually ask before installing Headroom or recommending it to a team.
What is Headroom?
Headroom is a menu bar app for macOS, Windows, and Linux, built for developers who use AI coding agents like Claude Code and ChatGPT (previously Codex). It reversibly compresses the tool output, logs, and boilerplate that bloat each prompt, all locally on your machine: ~50% fewer tokens on the noisy items, typically 40-50% across a session, for up to 2x more usage on the plan you already pay for. It is built on the open-source Headroom CLI (https://github.com/headroomlabs-ai/headroom/).
Is Headroom on GitHub / open source?
Yes. Headroom's compression engine is the open-source Headroom CLI on GitHub at https://github.com/headroomlabs-ai/headroom/, free to self-install. The desktop app (headroom-desktop) is built on top of it with the endorsement of the CLI's maintainer; you can find it at https://github.com/gglucass/headroom-desktop.
What does Headroom do for Claude Code?
Headroom is a menu bar app that reduces Claude Code token usage by reversibly compressing tool output, boilerplate, and large inputs before Claude Code stores them in the conversation. The plan you already pay for lasts longer, and Claude can pull the original content back if it needs it.
Does Headroom keep quality intact?
Yes, within measurement error. On the open-source benchmark suite, compressed context scores 0.919 F1 with 98.2% recall on HTML extraction, retrieves 4/4 needles from JSON log haystacks, and slightly improves QA F1 on SQuAD v2 and HotpotQA. And because compression is reversible, the model can always pull the original content back if it needs it.
Is Headroom's compression lossy?
No. Headroom's compression is reversible. When it shrinks a tool output or an older message, it includes a small retrieval tool that lets Claude pull back the original content on demand, so nothing is actually thrown away. Retrieval only fires when the model actually needs that detail, so instead of re-paying for the full content on every turn, you carry the compressed version and expand the occasional slice once, which is where the net savings come from.
Does Headroom break Anthropic's prompt cache?
No. Headroom is designed to preserve the cached prefix of your conversation. Tool outputs are compressed before they enter the conversation history, and stale messages later in the thread are compressed without altering the prefix Anthropic has already cached. The maintainer of the underlying Headroom CLI has reported around a 97% prefix cache hit rate from production usage.
How much latency does Headroom add?
Production data from the underlying Headroom CLI puts median overhead at roughly 52 milliseconds per request, on par with a single network round-trip and small compared to the seconds Claude itself takes to respond. Most people do not notice it.
Does Headroom send my prompts to your servers?
No. Headroom is privacy-first and runs locally on your machine, so your prompts do not need to be shipped to a Headroom server for optimization.
Who is Headroom for?
Headroom is designed for developers who rely on Claude Code or ChatGPT and want up to 2x as much usage on the plan they already pay for by cutting token waste and keeping large codebase sessions efficient without changing their workflow.
Does Headroom help with sub-agent token errors?
Yes. Sub-agents in Claude Code lose the parent session's prefix-cache benefit and can hit their own token limits quickly once tool output piles up. Headroom compresses sub-agent tool output the same way it compresses the main session, so the same task fits in fewer tokens.
What is Ponytail, and is it a Claude Code skill?
Ponytail is one of Headroom's one-click add-ons: a skill that nudges Claude Code and ChatGPT to write the least code possible, attacking the output-token side of the bill that input-focused tools leave untouched. It works with both Claude Code and ChatGPT, supports intensity levels (lite, full, ultra), and turns on from the Add-ons screen in the Headroom app.
Does Headroom work with OpenAI Codex?
Yes. Codex is now part of the ChatGPT app, and Headroom supports it as a first-class connector alongside Claude Code. Enable the ChatGPT connector in the app and Headroom routes the Codex CLI through the same local optimization proxy, compressing tool output and boilerplate before it reaches the model. It also tracks your ChatGPT subscription usage windows so you can see how much of your 5-hour and weekly limits you have left.
Does Headroom work with the Claude desktop app?
No. Headroom works with the Claude Code CLI and the Claude Code IDE extensions (such as the VS Code extension), but not with the Claude desktop app. The desktop app does not route its traffic through Headroom's local proxy, so its usage cannot be optimized.
Does Claude Code's Remote Control work with Headroom?
No, and it is not something Headroom can change. Since Claude Code 2.1.196, Anthropic hides the /remote-control command whenever ANTHROPIC_BASE_URL points at anything other than api.anthropic.com, and that variable is how Headroom routes Claude Code through its local proxy. The command is disabled inside Claude Code before any request is sent, so no proxy setting brings it back. If you need Remote Control, quit Headroom from the menu bar, which removes the routing variable, then start Claude Code in a new terminal and it behaves exactly as it did before Headroom. Launch Headroom again when you are done to get your optimization back. For a single session without quitting, run ANTHROPIC_BASE_URL= claude.
Which platforms does Headroom support?
Headroom runs on macOS, Windows, and Linux. The macOS build is universal (Apple silicon and Intel), signed and notarized. Windows ships as an x64 installer; it is not code-signed yet, so SmartScreen warns on first run and you dismiss it with More info, then Run anyway. Linux ships as a .deb and an AppImage for x86_64, built against glibc 2.39, so it needs Ubuntu 24.04 or newer and will not start on Ubuntu 22.04 or Debian 12. All three update themselves. The open-source Headroom CLI is separate and runs anywhere Python does.
Is Headroom for desktop related to Headroom CLI?
Yes. Headroom for desktop is based on the open-source Headroom CLI project (https://github.com/headroomlabs-ai/headroom/), and headroom-desktop is created with the endorsement of the Headroom CLI maintainer.
Isn't this just a paid wrapper around an open-source project?
Headroom's compression engine is the open-source Headroom CLI (https://github.com/headroomlabs-ai/headroom/), which is free to self-install. The desktop app was built with the endorsement of the CLI's creator, Tejas Chopra. You're paying for the packaged desktop app for macOS, Windows, and Linux, signed and notarized macOS builds, automatic updates, the menu-bar UI and stats, and ongoing support, not for the open-source engine itself.
How much does Headroom cost?
Every plan starts with a 7-day free trial. Paid plans match your Claude or ChatGPT tier and are priced at a small fraction of the subscription they stretch: since Headroom can stretch your usage up to 2x, each plan pays for itself many times over. See the pricing section on the homepage for current numbers; new subscribers get 50% off their first 3 months on every plan.
How does the free trial work?
Download the app, enter your email, and your 7-day free trial starts in the app, no credit card required. During the trial you get full optimization, and your coding tools keep working normally throughout. When the trial ends, pick the plan that matches your Claude or ChatGPT tier to keep optimizing; there is no free plan after the trial.
Is Headroom safe to install, and can I uninstall it easily?
Headroom is a menu bar app for macOS, Windows, and Linux (the macOS build is signed and notarized) that routes Claude Code and ChatGPT through a local proxy on your machine. Turn it off or quit it and they talk to their APIs exactly as before; your setup is untouched. Uninstalling is dragging the app to the Trash on macOS, or the normal uninstall path on Windows and Linux.
How should I evaluate whether Headroom is worth it?
Start with the 7-day free trial, compare token usage before and after installing it, and look at sessions that involve verbose tool output like code search, logs, HTML, or long documentation, since those are the areas where optimization tends to help most. If your normal workload lands around 50% lower token usage, that is effectively about 2x as much Claude Code usage on the Claude plan you already pay for.
Still comparing options?
Read the guide to reducing Claude Code costs, the Claude Code usage guide, or the Claude Code usage limits page if you keep hitting the 5-hour cap. On Codex, see the guide to reducing Codex costs and the Codex usage limits page. If you want context on why the bill feels high, see why Claude Code is so expensive or how to reduce Claude API costs. Or check the benchmark section and install Headroom to measure on a session of your own.
