gglucass/headroom-desktop

What it solves

Headroom is designed to reduce the token costs associated with using AI coding assistants like Claude Code and OpenAI Codex. It targets the "bloat" in prompts—specifically tool outputs, logs, and boilerplate—that increases costs without adding necessary value to the AI's reasoning process.

How it works

Headroom operates as a local-first proxy between your coding client and the LLM API. It intercepts requests and responses through a two-hop local proxy system (using a Rust intercept proxy and a Python optimization backend) to compress content before it is sent to the API.

Key mechanisms include:

• Managed Python Runtime: It installs an isolated Python environment to run optimization tools without affecting the system Python.
• Token-Saving Tools: It bundles tools like headroom for prompt optimization and rtk for compressing CLI output.
• Reversible Compression: It compresses data such that the model can still pull the original content back if needed.
• Client Integration: It automatically configures clients (like Claude Code via settings.json and Codex via config.toml) to route traffic through the local proxy.

Who it’s for

Developers using Claude Code or OpenAI Codex who want to lower their API costs and extend their token limits without changing their coding workflow.

Highlights

• Significant Cost Reduction: Benchmarks show up to 94.9% compression for HTML extraction and 87.6% for JSON logs.
• Zero Host Pollution: The app manages its own dependencies and completely reverses all system and config changes upon quitting or uninstalling.
• Local-First Privacy: All processing happens on 127.0.0.1 before the final upstream call to the API.
• Analytics Dashboard: Provides daily and monthly savings charts and per-client token statistics.
• Conservative Code Protection: Intentionally avoids compressing active source code to ensure accuracy in debugging and analysis tasks.