How to install Headroom for Claude Code and ChatGPT Codex

Install the Headroom app

1. Download Headroom for macOS, Windows, or Linux.
2. Install it: drag it into Applications on macOS, run the setup installer on Windows, or install the .deb (or run the AppImage) on Linux.
3. Open it once. It sets itself up, lives in the menu bar or tray, and routes Claude Code through its local proxy. To add ChatGPT Codex, turn on its connector in the app.

The Windows installer is signed. The Linux build needs Ubuntu 24.04 or newer (glibc 2.39). If a coding agent is doing the install for you, point it at the agent runbook, which covers detection, the install command, and the one step that stays with you.

What the app adds

• Always on. Every Claude Code and ChatGPT Codex session is compressed without you starting anything, including after a reboot.
• Automatic updates for the app and the Headroom engine it runs.
• Usage windows and savings in the menu bar: how much of your 5-hour and weekly limits is left, and tokens saved per day.
• One-click add-ons: RTK for terminal output, MarkItDown for PDFs and Office documents, Ponytail for leaner code, and more.
• Local processing. Compression runs on your machine; your prompts go to Anthropic or OpenAI as before, not to a Headroom server.

Install the open-source Headroom CLI

The Headroom CLI (Apache 2.0) is free. On a clean machine with Python 3.10 or newer:

1. Install the package: pip install "headroom-ai[all]". Node and Docker images are also available.
2. Run your agent through it: headroom wrap claude for Claude Code or headroom wrap codex for the Codex CLI. Alternatively start a drop-in proxy with headroom proxy --port 8787, or register it as an MCP server with headroom mcp install.
3. Keep that process running for the whole session, and repeat the wrap or proxy step in each new terminal.

On a well-behaved machine that is all it takes. What the app handles for you is the upkeep:

• Starting it. Close the terminal and the proxy stops; the next session runs uncompressed until you start it again.
• Updating it. There is no auto-update, so run pip install -U headroom-ai now and then to pick up compression improvements and fixes.
• Python. It can clash with another project's Python version or virtualenv. headroom: command not found after installing usually means the pip scripts directory is not on your PATH.
• Seeing results. There is no dashboard, so checking that it runs and what it saves means reading its output.

On corporate networks, SSL inspection can also break the install or block the model files it downloads.

Which to choose

Choose the CLI if you want full control, want to script Headroom into your own pipeline, or run a platform the app does not cover yet (Linux on ARM, or a distribution older than Ubuntu 24.04). Choose the app if you want it running in every session without thinking about it. Either way the savings are the same: about 50% fewer tokens on the noisy items it compresses, typically 25-50% across a session. The benchmarks show where they come from, and Headroom desktop vs CLI compares the two in more detail.

For other ways to cut usage, see the Claude Code cost guide and the Codex cost guide. The FAQ covers pricing, privacy, and the prompt cache.