Headroom Desktop — cut Claude Code & Codex token costs by ~50%
Headroom is a macOS menu bar app that cuts Claude Code and OpenAI Codex token costs by ~50% — without changing how you code. 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.
Pricing: Headroom has a free tier and paid plans — see pricing. The desktop shell in this repo is MIT-licensed; account features and paid plans are opt-in.
Stable: macOS 14 (Sonoma) or later on Apple Silicon (M1 or later)
Preview: Linux x86_64 builds are experimental and currently support the core proxy flow only.
Install
- Go to the latest release
- On macOS, download the
.dmgfile (for exampleHeadroom_0.2.9.dmg) - Open the DMG, drag Headroom to Applications
- Launch Headroom — it appears in your menu bar and walks you through setup
Headroom is signed and notarized, so macOS will open it without Gatekeeper warnings.
Linux preview artifacts are published on the same release page. Today they are best treated as a preview for the core Headroom proxy, Claude Code routing, and RTK flow. Headroom Learn is not supported yet on Linux preview builds.
Note: Headroom supports Claude Code and Codex (CLI and desktop app). Support for additional clients is planned.
Headroom is a local-first desktop tray app that routes your coding clients through a local optimization pipeline. The stable target is macOS; Linux builds are currently experimental. 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 and does three things:
- Installs a managed Python runtime into Headroom-owned storage — isolated from your system Python, no
pip install --userpollution. - Chains token-saving tools (
headroomfor prompt optimization,rtkfor CLI output compression) between your client and the LLM API. - 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.
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.
On install:
- Downloads a self-contained Python runtime (~2 GB) under
~/Library/Application Support/Headroom. Your system Python is untouched. - Adds a
PreToolUsehook to~/.claude/settings.jsonand a script at~/.claude/hooks/headroom-rtk-rewrite.shso Claude Code routes through Headroom. A timestamped backup ofsettings.jsonis written before any edit. - For Codex, adds a Headroom provider block to
~/.codex/config.tomland anOPENAI_BASE_URLexport 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. - Creates
~/Library/Application Support/Headroomfor logs, caches, and per-client setup state. - Stores your Headroom session token in the macOS Keychain 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 managedbindirectory (under~/Library/Application Support/Headroom) toPATHsortkis 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, and the managed shell blocks. 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
| Tool | What it does | Default |
|---|---|---|
| headroom | Prompt optimization pipeline (Python) | Required |
| rtk | Rewrites Claude Code bash commands to strip noise before it reaches the context window | Opt-in add-on |
| markitdown | Converts PDFs and Office documents to clean Markdown before the agent reads them | Opt-in add-on |
| ponytail | Nudges the agent toward leaner, less over-engineered code | Opt-in add-on |
Tool inclusion policy: only tools that run entirely locally, inside Headroom-managed storage, with a stable CLI surface make it in. No cloud dependencies, no host profile mutations. See research/tool-compatibility-matrix.md.
Compression benchmarks
Numbers from the headroom open-source library that powers the optimization pipeline, summarized from the current published benchmarks page.
Current benchmark summary
| Benchmark | What it tests | Result |
|---|---|---|
| Scrapinghub article extraction | Extract article bodies from 181 HTML pages while removing boilerplate | 0.919 F1, 98.2% recall, 94.9% compression |
| SmartCrusher JSON compression | Find a critical error in 100 production log entries after compression | 4/4 correct, 87.6% compression |
| QA accuracy preservation | Ask the same questions on raw HTML vs. extracted content | 0.87 F1 vs. 0.85 baseline, 62% exact match vs. 60% |
| Multi-tool agent test | 4-tool agent investigating a memory leak with compressed tool output | 6,100 vs. 15,662 tokens sent, 76.3% compression, same findings |
Benchmark details
| Benchmark | Setup | Accuracy | Compression |
|---|---|---|---|
| HTML extraction | Scrapinghub article extraction benchmark, 181 pages | 0.919 F1, 0.879 precision, 0.982 recall | 94.9% |
| JSON compression | 100 production log entries, critical error at position 67 | 4/4 correct answers | 87.6% |
| QA preservation | SQuAD v2 + HotpotQA on raw HTML vs. extracted content | +0.02 F1, +2% exact match vs. raw HTML | — |
| Multi-tool agent test | Agno agent with 4 tools investigating a memory leak | Same findings as baseline | 76.3% |
What compresses well vs. what doesn't
| Content type | Typical savings | Notes |
|---|---|---|
| JSON arrays (search results, API responses, DB rows) | 86–100% | Primary use case |
| Structured logs | 82–95% | Errors and anomalies always preserved |
| Agentic conversations (25–50 turns) | 56–81% | |
| Plain text / documentation | 43–46% | Cost savings only, adds latency |
| Source code | Mostly passthrough | Code in active messages is protected by default — see limitations |
Limitations worth knowing
- Code compression is intentionally conservative. Code in recent messages (last 4 by default) and any conversation where the user is asking about code (
analyze,debug,fix, etc.) is never compressed. The savings from code come from dropping old, no-longer-relevant messages — not from stripping function bodies. - Short content is skipped. Arrays under 5 items and content under 200 tokens pass through unchanged.
- Text compression (LLMLingua) adds latency. It requires a ~2 GB model download on first use and doesn't break even on fast models. Useful for cost reduction, not speed.
- Plain-text RAG results pass through. Compression targets tool outputs and JSON; plain text in user messages is not compressed.
Full methodology and reproducible benchmarks: chopratejas/headroom benchmarks · limitations
Interesting design decisions
- Zero host pollution. Headroom owns its entire dependency tree. Uninstalling the app leaves your shell, your Python, and your PATH exactly as they were (except for the optional
rtkPATH addition, which is reversible). - Rust shell, Python brain. The Tauri/Rust layer handles tray lifecycle, managed installs, client detection, and update delivery. The optimization wor