Summary

Headroom Desktop is a macOS menu bar app that cuts Claude Code and OpenAI Codex token costs by ~50%. It targets developers using these AI coding assistants, enabling them to extend AI plan usage significantly by optimizing prompts and outputs locally, without altering their coding workflow.

How It Works

The app employs a local-first optimization pipeline. It reversibly compresses tool output, logs, and boilerplate using chained Python tools (headroom, rtk) before API calls. This pipeline runs within a self-contained, managed Python runtime isolated from the system, preventing host pollution and allowing on-demand decompression.

Quick Start & Requirements

• Install: Download .dmg for macOS (14+ Sonoma, Apple Silicon M1+) from releases. Linux x86_64 preview builds are experimental.
• Setup: Launch the app from Applications and follow the guided setup.
• Prerequisites: Stable use requires macOS 14+ on Apple Silicon. Linux preview supports core proxy flow only.

Highlighted Details

• Cost Savings: ~50% reduction in Claude Code/Codex token costs.
• Local-First: Manages its own Python runtime (~2 GB) and tools locally, isolated from system Python/PATH.
• Bundled Tools: headroom (prompt optimization), rtk (Claude Code bash compression), markitdown (document conversion), ponytail (code nudging).
• Performance: Benchmarks show high compression ratios (e.g., 94.9% HTML boilerplate, 87.6% JSON logs) with minimal accuracy loss.

Maintenance & Community

Features a robust release process with stable (main) and release candidate (staging) channels, enforced via CI/CD and branch protection. Versioning uses ./scripts/bump-version.sh. Development requires npm install, npm run tauri dev, and environment variables. No explicit community links (Discord/Slack) are provided.

Licensing & Compatibility

The desktop shell is MIT-licensed. Account features and paid plans are opt-in and managed via a separate, private backend. Stable on macOS 14+ (Apple Silicon); Linux is experimental.

Limitations & Caveats

Code compression is conservative, excluding recent messages or code-related queries. Text compression introduces latency, prioritizing cost savings over speed. Short content (under 200 tokens) and small arrays are bypassed. The core optimization logic is open-source, but associated web services for account management are proprietary.