Markdown version of https://extraheadroom.com/install-headroom-claude-code

# How to install Headroom for Claude Code and ChatGPT Codex

There are two ways to run Headroom with Claude Code and ChatGPT Codex. The desktop app for macOS, Windows, and Linux is one download with no Python or pip, and it keeps running in the menu bar from then on. The open-source Headroom CLI is free and runs anywhere Python does, but you install, start, and update it yourself. Both use the same compression engine: the app is built on the CLI, with its maintainer's endorsement.

## 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](/docs/for-agents), 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](/docs/add-ons):** [RTK](https://github.com/rtk-ai/rtk) for terminal output, [MarkItDown](https://github.com/microsoft/markitdown) for PDFs and Office documents, [Ponytail](/ponytail-claude-code) 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](https://github.com/headroomlabs-ai/headroom) (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 it in each new terminal, or run `headroom deploy` once to install the proxy as a background service and configure your agents.

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 a `wrap` or `proxy` session stops; the next session runs uncompressed until you start it again. `headroom deploy` avoids that with a background service you look after yourself.
- **Updating it.** The proxy tells you when a release is out; run `headroom update` and restart it 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.** `headroom dashboard` shows savings in your browser, but only while the proxy is running.

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](/#benchmarks) show where they come from, and [Headroom desktop vs CLI](/headroom-desktop-vs-cli) compares the two in more detail.

For other ways to cut usage, see the [Claude Code cost guide](/reduce-claude-code-costs) and the [Codex cost guide](/reduce-codex-costs). The [FAQ](/faq) covers pricing, privacy, and the prompt cache.