Headroom Desktop: a local proxy that compresses Claude Code and Codex prompts
Menu Bar App on MacOS and Windows that cuts Claude Code and Codex token costs by ~50%
At a glance
- What is it?
- gglucass/headroom-desktop is a Tauri menu bar app that routes coding clients through a two-hop local proxy and a managed Python pipeline. The desktop shell is MIT-licensed, but the app needs a paid Headroom account to run.
- Who is it for?
- Adopt Headroom Desktop if you already pay for Claude Code or Codex, work on macOS 14 or Windows 10 or later, and want a visible per-request record of what the pipeline compressed before you commit to a subscription. Skip it if you need a fully open source stack: the repository shell is MIT, but the README states the app requires a Headroom account and an active plan, and the managed Python runtime is roughly 3 GB on disk under the platform app-data directory.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The bill problem Headroom Desktop targets
Coding agents resend a lot of text that the model has already seen. Tool output, log lines, and repeated boilerplate go back into the context on the next turn, and you pay input token rates for all of it. Headroom Desktop is built for the person who notices that on an invoice and wants the fix to be invisible to their editor. The README states the app cuts Claude Code and ChatGPT / Codex token costs by roughly 50 percent by reversibly compressing that material, and that the model can request the original content back when it needs it. It is not a general prompt library or an evaluation harness. It is a tray app that sits between your client and the API, and the audience is individual developers and small teams already paying for one of the supported plans. The README also lists OpenCode and Grok Build as routed clients, so the target is anyone whose daily loop runs through one of those four tools.
The two-hop proxy topology on ports 6767 and 6768
The architecture is a fixed Rust intercept proxy plus a Python backend that does the actual work. Clients are pointed at port 6767, which the README describes as always-on and never moving, so client configuration only ever references that one port. The intercept proxy forwards locally to port 6768, where a managed Python backend runs the headroom and rtk pipeline, optimizes the request and response, and then calls the real upstream API. Port 6768 is configurable, and the README states that if the default is already bound the proxy probes 6768 through 6790 and falls back to the first free port. That is a sensible split: the stable surface stays fixed while the internal hop can move. Routing is configured in more than one place so both interactive shells and GUI launches pick it up. Claude Code gets an env block in ~/.claude/settings.json plus an export inside a managed shell block fenced with # >>> headroom:... >>> markers. Codex uses a provider block in ~/.codex/config.toml plus OPENAI_BASE_URL. OpenCode gets Headroom base URLs for its anthropic and openai providers, and Grok Build gets a GROK_CLI_CHAT_PROXY_BASE_URL export. The README states that nothing leaves 127.0.0.1 except the final upstream call, which goes to the same API the client would have called directly.
Installing Headroom Desktop and confirming the proxy is live
The README gives two install paths on macOS: a Homebrew cask and a manual download. The cask is the shortest route.
brew install --cask headroomManual installs come from the latest release page. macOS gets a .dmg that you drag into Applications, Windows gets an _x64-setup.exe installer, and Linux gets either an .AppImage with a built-in updater or a .deb that updates only by downloading a newer file. Requirements are macOS 14 or later on Apple Silicon or Intel, Windows 10 or later on x64, and on Linux x86_64 with glibc 2.39 or newer plus a running secret-service keyring provider such as gnome-keyring or kwallet for sign-in. After launch the app appears in the menu bar or system tray and walks through setup. The README notes that the first launch fetches the heavy Python components, and that the runtime is about 3 GB on disk under ~/Library/Application Support/Headroom or the platform app-data directory. The one check that tells you the pipeline is actually up is the stats endpoint.
curl -s http://127.0.0.1:6767/statsJSON back means the proxy is running. The README also points coding agents at an agent runbook at extraheadroom.com/docs/for-agents, which covers every step that works from a shell plus the one sign-in step that stays with the human.
What Headroom writes to your machine, and how it comes back out
The README publishes the full list of locations the app touches, and the install screen shows the same list. On install it downloads the self-contained Python runtime, adds a PreToolUse hook to ~/.claude/settings.json, and writes a script at ~/.claude/hooks/headroom-rtk-rewrite.sh. The README states a timestamped backup of settings.json is written before any edit, which is the detail that makes this tolerable. The uninstall flow is documented as reversing every item, and the README says that on quit or uninstall the redirects are removed so clients talk to the upstream API directly again. That is a stronger uninstall story than most tools in this category offer, but it is also the part you cannot verify from the README alone. If you are evaluating Headroom Desktop, the first thing to inspect is your own ~/.claude/settings.json before and after a quit, and your managed shell block, which should no longer contain the headroom export.
The paid shell: what is MIT and what is not
This is the part that surprises people who find the repository through GitHub search. The desktop shell is MIT-licensed and open source, but the README states plainly that Headroom is a paid subscription app with a 7-day free trial, no credit card required, plans from $4 per month or $3 per month billed annually. The app requires a Headroom account and an active plan to run. So the licence covers the Tauri shell, the React frontend, and the Rust intercept proxy, while the optimization backend is a managed Python runtime fetched on first launch. That is a normal split for a commercial product with an open client, but it means you cannot fork this and get the compression for free. The repository layout supports the same reading: src-tauri/ and src/ hold the shell, packaging/ and scripts/ hold release tooling, and the .env.example file references an account API base URL at extraheadroom.com/api/v1, an Aptabase app key, a Sentry DSN, and Tauri updater keys. Those are all shell-side concerns. Nothing in the repository contents given here is the optimizer itself.
Where Headroom Desktop is the wrong tool
The clearest limitation is the Linux story. The README states that the Linux runtime installs a proxy-focused subset of the Python stack, so the memory and ML extras present in the macOS and Windows builds are absent there. If your evaluation of a token optimizer depends on those extras, Linux is not the platform to judge it on. The second constraint is sign-in. Linux needs a running secret-service keyring provider, and the README frames sign-in as the step that stays with the human even in the agent runbook, so a headless CI box or a container running Claude Code unattended is not a supported shape for this app. The third is the 3 GB managed runtime under the app-data directory. On a machine with a small boot volume, or in an environment where you cannot write to ~/Library/Application Support, the install will not complete. Finally, if you are not already paying for one of the supported clients, there is nothing here to compress; Headroom Desktop optimizes traffic from Claude Code, Codex, OpenCode, and Grok Build, and the README says support for additional clients is planned, not shipped.
Headroom Desktop versus editing your client config by hand
The honest alternative is doing nothing and paying full input token rates, or trimming context yourself with CLAUDE.md files, .claudeignore style exclusions, and shorter tool output. That approach costs no subscription and no 3 GB of disk, and it keeps your settings.json untouched. The difference in approach is where the compression happens. Manual trimming is a habit you maintain per project and it is lossy in the sense that you decide what the model never sees. Headroom Desktop intercepts at the proxy layer instead, so the decision is made per request by the pipeline and the README states the original content can be pulled back on demand. That reversibility is the actual product claim, and it is the thing to test during the trial. A second alternative is a plain HTTP proxy you configure yourself, which gives you full control but none of the savings analytics, the per-client token stats, or the addons screen the README screenshots show. The trade is convenience and visibility against control and zero cost.
Release cadence, upgrade path and what to verify first
The last push to the repository was on 2026-09-10, and the recent releases cluster on the same day: v0.9.16-rc.1 tagged as staging, v0.9.15 as stable, and v0.9.15-rc.8 as staging. That pattern, a stable release followed by release candidates carrying the next minor version, tells you the project ships from release branches and keeps a staging channel separate from stable. The package.json version field reads 0.9.15, matching the latest stable tag. Upgrades are handled by the app itself: the README states all install paths self-update via the built-in updater, the Homebrew cask stays current with each release, and the Linux .deb is the exception because it updates only by downloading a newer file. Every stable release ships macOS, Windows, and Linux from the same tag, so the platform builds should stay in step. The upgrade cost that matters is not the download but the re-application of client config: each release that changes routing has to re-edit ~/.claude/settings.json, ~/.codex/config.toml, and the managed shell block. The README documents the settings.json backup, so if a release misbehaves you have a timestamped file to restore from, but the README does not document rollback for the Codex provider block or the OpenCode config.
Editorial conclusion
Adopt Headroom Desktop if you already pay for Claude Code or Codex, work on macOS 14 or Windows 10 or later, and want a visible per-request record of what the pipeline compressed before you commit to a subscription. Skip it if you need a fully open source stack: the repository shell is MIT, but the README states the app requires a Headroom account and an active plan, and the managed Python runtime is roughly 3 GB on disk under the platform app-data directory. Before paying, run the 7-day trial and check two things: that curl -s http://127.0.0.1:6767/stats returns JSON while a session is active, and that quitting the app removes the headroom block from ~/.claude/settings.json and the export from your managed shell block.
Frequently asked questions
Is Headroom Desktop free?
No. The README states Headroom is a paid subscription app with a 7-day free trial, no credit card required, and plans from $4 per month or $3 per month billed annually. The desktop shell in the repository is MIT-licensed, but the app requires a Headroom account and an active plan to run.
Which coding clients does Headroom Desktop work with?
The README lists Claude Code, ChatGPT / Codex (CLI and desktop app), OpenCode, and Grok Build. Support for additional clients is described as planned, not shipped.
Does Headroom Desktop work on Windows?
Yes. The README states Windows 10 or later on x64 is supported, and the manual install path is an _x64-setup.exe installer from the latest release. Stable releases ship all three platforms from the same tag.
What ports does Headroom Desktop use?
Port 6767 is the fixed intercept port that clients are pointed at, and port 6768 is the internal hop to the Python optimization backend. The README states that if 6768 is already bound, the proxy probes 6768 through 6790 and uses the first free port.
Does Headroom Desktop send my code anywhere?
The README states nothing leaves 127.0.0.1 except the final upstream call, which goes to the same API your client would have called directly. The pipeline runs locally between the intercept proxy and the managed Python backend.
How do I check whether Headroom Desktop is running?
Run curl -s http://127.0.0.1:6767/stats. The README states that JSON back means the proxy is running.
Community notes