Headroom Desktop - cut Claude Code & Codex token costs by ~50%

Headroom is a desktop tray app for macOS, Windows, and Linux that cuts Claude Code and ChatGPT / Codex token costs by ~50% - without changing how you code. It also routes OpenCode and Grok Build through the same pipeline. It runs a local-first optimization pipeline that reversibly compresses the tool output, logs, and boilerplate that bloat every prompt, so the AI plan you already pay for stretches about 2x further. Nothing the model needs is lost - it can pull the original content back on demand.

Paid product. Headroom is a paid subscription app (7-day free trial, no credit card required; plans from $4/mo, or $3/mo billed annually) - see pricing. The desktop shell in this repo is MIT-licensed and open source, but the app requires a Headroom account and an active plan to run.

macOS: 14 (Sonoma) or later, Apple Silicon or Intel (universal build)

Windows: Windows 10 or later, x64

Linux: x86_64, glibc 2.39 or newer (Ubuntu 24.04, Debian 13), plus a running secret-service keyring provider (gnome-keyring or kwallet) for sign-in

Install

Option A - Homebrew (macOS):

brew install --cask headroom

Option B - manual download:

1. Go to the latest release
2. macOS: download the .dmg (for example Headroom_0.9.3_mac.dmg), open it, drag Headroom to Applications
3. Windows: download and run the _x64-setup.exe installer
4. Linux: download the .AppImage (has the built-in updater) or the .deb (same build, updates only by downloading a newer one)
5. Launch Headroom - it appears in your menu bar / system tray and walks you through setup

Headroom is signed and notarized on macOS, so it opens without Gatekeeper warnings. All install paths self-update via the app's built-in updater; the Homebrew cask stays current with each release too.

Every stable release ships all three platforms from the same tag. The Linux runtime installs a proxy-focused subset of the Python stack, so the memory and ML extras that the macOS and Windows builds ship are absent there.

For AI agents

If you are a coding agent installing or diagnosing Headroom for your user, follow the agent runbook - every step that works from a shell, plus the one sign-in step that stays with the human. Detect a running install with curl -s http://127.0.0.1:6767/stats (JSON back = running). Machine-readable product summary: extraheadroom.com/llms.txt; markdown docs by appending .md to any docs URL.

Note: Headroom supports Claude Code, ChatGPT / Codex (CLI and desktop app), OpenCode, and Grok Build. Support for additional clients is planned.

Headroom is a local-first desktop tray app that routes your coding clients through a local optimization pipeline. Stable builds ship for macOS, Windows, and Linux. It installs and manages a self-contained Python runtime, bundles proven token-saving tools, and surfaces savings analytics - all without touching your system environment.

How it works

Headroom sits in your menu bar (system tray on Windows and Linux) and does three things:

1. Installs a managed Python runtime into Headroom-owned storage - isolated from your system Python, no pip install --user pollution.
2. Chains token-saving tools (headroom for prompt optimization, rtk for CLI output compression) between your client and the LLM API.
3. Shows you the math - daily and monthly savings charts, per-client token stats, and pipeline health.

The app ships as a slim Tauri shell (~a few MB). Heavy Python components are fetched on first launch and kept in ~/Library/Application Support/Headroom (or the platform's app-data directory on Windows and Linux).

Proxy topology

Headroom is a two-hop local proxy. Nothing leaves 127.0.0.1 except the final upstream call, which goes to the same API your client would have called directly.

Claude Code / ChatGPT (Codex) / OpenCode / Grok Build
    |  ANTHROPIC_BASE_URL = http://127.0.0.1:6767
    |  OPENAI_BASE_URL    = http://127.0.0.1:6767/v1
    v
:6767  Rust intercept proxy (always-on, fixed port)
    |  forwards locally
    v
:6768  managed Python backend (headroom + rtk pipeline)
    |  optimizes request/response, then calls the real API
    v
api.anthropic.com / api.openai.com

• :6767 is the fixed intercept port. Clients are pointed at it, so it never moves. It is the only port your client config references.
• :6768 is the internal hop between the intercept proxy and the Python optimization backend. It is configurable and, if the default is already bound, the proxy probes 6768-6790 and falls back to the first free port.
• Routing is set two ways so both interactive shells and GUI launches pick it up: an env block in ~/.claude/settings.json (Claude Code) and an export in 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 in its config, and Grok Build gets a GROK_CLI_CHAT_PROXY_BASE_URL export in the managed shell block.
• On quit or uninstall, every one of these redirects is removed and clients talk to the upstream API directly again (see below).

What Headroom changes on your system

Full disclosure of every location Headroom writes to, so you can decide before installing. The install screen in the app shows the same list, and the uninstall flow reverses every item. Paths below are the macOS locations; Windows and Linux use the platform equivalents.

On install:

• Downloads a self-contained Python runtime (~3 GB on disk) under ~/Library/Application Support/Headroom. Your system Python is untouched.
• Adds a PreToolUse hook to ~/.claude/settings.json and a script at ~/.claude/hooks/headroom-rtk-rewrite.sh so Claude Code routes through Headroom. A timestamped backup of settings.json is written before any edit.
• For Codex, adds a Headroom provider block to ~/.codex/config.toml and an OPENAI_BASE_URL export to your managed shell block so the Codex CLI and desktop app route through the local proxy. The TOML block is fenced with # >>> headroom:... >>> markers, a backup is written before any edit, and existing Codex threads are retagged to the managed provider.
• For OpenCode, points the anthropic and openai provider base URLs in OpenCode's config at the local proxy and installs a small transport plugin. A backup is written before any edit.
• For Grok Build, adds a GROK_CLI_CHAT_PROXY_BASE_URL export to the managed shell block.
• Creates ~/Library/Application Support/Headroom for logs, caches, and per-client setup state.
• Stores your Headroom session token in the macOS Keychain (Windows Credential Manager / Linux secret-service on those platforms) under services prefixed com.extraheadroom.headroom.
• If you opt into "launch at login," installs a LaunchAgent plist at ~/Library/LaunchAgents/. Never added otherwise.
• Adds a managed block to your shell profile (.zshrc, .zprofile, etc.) that prepends Headroom's managed bin directory (under ~/Library/Application Support/Headroom) to PATH so rtk is available in your terminals. Every managed block is fenced with # >>> headroom:... >>> markers and can be removed by hand if you prefer.

On quit (or pause): Headroom tears down everything that would intercept your clients - the Claude Code hook entry and hook script, the ANTHROPIC_BASE_URL and OPENAI_BASE_URL redirects, the Codex provider block in ~/.codex/config.toml, the OpenCode provider URLs and plugin, and the managed shell blocks (including the Grok Build export). Codex threads are retagged back to their native provider. Claude Code and Codex behave exactly as they did before Headroom was launched. The Python runtime, logs, and keychain entries stay on disk so the next launch is fast.

On uninstall (Settings → Uninstall Headroom): Everything listed above is removed, including the LaunchAgent plist, ~/Library/Preferences/com.extraheadroom.headroom*, ~/Library/Caches/com.extraheadroom.headroom, and the keychain entries. The uninstall dialog in the app shows the full list before you confirm.

If the proxy dies unexpectedly, a watchdog restarts it; after repeated failures it auto-pauses and strips interception so your clients keep working without intervention.

Bundled tools