Quickstart

1. Install Headroom

Download the installer for your operating system from the download page.

• macOS: move Headroom to Applications and open it. With Homebrew, run brew install --cask headroom, then open -a Headroom.
• Windows: run the installer and open Headroom.
• Linux: install the .deb package or run the AppImage. A desktop session and a secret-service keyring, such as gnome-keyring or kwallet, are required for sign-in.

Headroom runs from the menu bar or system tray. Keep it running while using your coding agent.

2. Sign in and finish setup

Enter your email address in Headroom and confirm the sign-in code sent to you. Allow the initial runtime and compression-model downloads to finish. Download time depends on your connection.

Headroom processes compression locally, then forwards requests to your configured AI provider.

3. Connect your coding agent

1. Enable the connector for Claude Code or ChatGPT Codex in Headroom.
2. Open a new terminal. Existing terminals can retain the environment from before setup.
3. Start a new coding-agent session in that terminal. In the Codex CLI, run /hooks to review and trust Headroom's routing guard; repeat this if the guard changes.

Headroom configures Claude Code through ~/.claude/settings.json and Codex through ~/.codex/config.toml, with shell exports where available. The Codex CLI, desktop app, and IDE extension share that configuration. Any tool that launches an agent CLI for you, such as an IDE extension or an agent runner, inherits the same routing without extra setup; see which IDEs and agent runners work. Claude Code inside the Claude desktop app does not use the supported routing configuration and cannot be optimized.

4. Verify routing

Check the connector status in Headroom first. The commands below inspect shell exports; they do not check the agent's configuration files.

macOS or Linux:

# Claude Code
echo "$ANTHROPIC_BASE_URL"
# ChatGPT Codex
echo "$OPENAI_BASE_URL"

Windows PowerShell:

# Claude Code
$env:ANTHROPIC_BASE_URL
# ChatGPT Codex
$env:OPENAI_BASE_URL

For the default local setup, Claude Code uses http://127.0.0.1:6767 and Codex uses http://127.0.0.1:6767/v1. An empty shell variable does not prove routing failed: the agent can use its managed configuration file instead. If routing is uncertain, inspect the connector status and verify traffic below.

Ask the agent to inspect a project file or run an existing test. Check Headroom's connector status and Activity view for recorded optimizations. For a direct request-count check, use the agent runbook. A request can pass through Headroom without producing savings if it contains little compressible content.

Next steps

• Tutorials and use cases: try a workflow and check its results.
• Add-ons: choose optional tools for additional savings.
• Troubleshooting: diagnose missing requests, setup errors, or zero savings.