FAQ
These are the questions people usually ask before installing Headroom or recommending it to a team.
Headroom is a menu bar app for macOS, Windows, and Linux, built for developers who use AI coding agents like Claude Code and ChatGPT 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 25-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/).
Typical Claude Code sessions come out 25-50% lighter on input tokens. Sessions heavy on logs, test output, search results, and docs do better; sessions where the agent mostly thinks and writes code save less, because there is less noise to remove. Savings on ChatGPT (Codex) are currently lower than on Claude Code, because Codex already trims much of its own tool output. The app shows your own savings live from the first session, so you will know within a day or two where you land.
Claude and ChatGPT already cache the unchanged part of your conversation and bill it at a steep discount. Headroom measures savings against the new input you pay full price for and leaves cached tokens out of the percentage, so the number is not inflated. Your bill also includes output tokens, which input compression does not touch.
Probably, in both directions. Claude Code and ChatGPT update often, and each release changes what they send. We ship compression improvements every week, and the app always shows your current rate.
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.
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.
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.
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.
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.
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.
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.
Headroom is designed for developers who rely on Claude Code or ChatGPT Codex 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.
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.
Ponytail is one of Headroom's one-click add-ons: a skill that nudges Claude Code and ChatGPT Codex 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 Codex, supports intensity levels (lite, full, ultra), and turns on from the Add-ons screen in the Headroom app.
Yes. Codex is now part of the ChatGPT app, and Headroom supports it as a first-class connector alongside Claude Code. Enable the ChatGPT Codex 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.
Usually yes, with no extra setup. Headroom configures the agent, not your editor: turning on a connector writes the routing into that agent's own config file, so anything that launches Claude Code, Codex, OpenCode, or Grok for you inherits it automatically. That covers the Claude Code IDE extensions (VS Code, JetBrains, and VS Code forks such as Cursor and Windsurf), agent runners and worktree managers such as bb and Conductor, and headless runs like claude -p from a script or a cron job. The exception is a tool that calls the model API directly with its own HTTP client instead of running the agent CLI, such as Cline, Roo Code, or Aider. Those never read the agent's config, so Headroom can only route them if the tool has its own base URL setting you can point at http://127.0.0.1:6767.
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. That covers Chat, Cowork and the Code tab alike. Codex inside the ChatGPT desktop app does work. The Compatibility page in the docs lists every app we have checked, with workarounds.
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.
Headroom runs on macOS, Windows, and Linux. The macOS build is universal (Apple silicon and Intel), signed and notarized. Windows ships as a signed x64 installer. 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.
It lowers the energy each coding task takes. Every token Headroom removes is one a data center never processes, and in one week of September 2026 it kept 4.76 billion tokens out of data centers: an estimated 19 to 192 kWh a year for the average user, based on published per-token energy estimates. Total energy only falls if the freed capacity isn't spent on more work.
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.
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.
The open-source Headroom CLI is free (Apache 2.0) and you run it yourself. The desktop app is free for a 7-day trial, with no credit card, and then needs a paid plan to keep compressing; there is no free tier after the trial.
Not for the desktop app. Download it for macOS, Windows, or Linux, open it once, and it installs and runs everything it needs itself. Python 3.10+ and pip are only needed for the open-source Headroom CLI (pip install "headroom-ai[all]").
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 and any running offer.
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.
One license is for one person. Install Headroom on as many of your own computers as you like and sign in with the same Headroom email on each; moving to a new computer needs nothing from us. Use it with your own Claude and ChatGPT accounts, including a separate work and personal account. Each additional person needs their own license. AppSumo buyers can buy a license add-on and assign it to a colleague's email from their Headroom activation page.
Headroom manages routing through local configuration. For full cleanup, open Settings in Headroom, click Uninstall Headroom, review the list, and confirm Uninstall and quit. Quitting or deleting the app alone does not remove all managed integrations and local data. How releases are signed, how to verify a download and how to report a vulnerability are on the Security page in the docs.
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.
Read the guide to reducing Claude Code costs, 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.
7-day free trial · no credit card required
