Privacy-first analytics pixel

For AI agents: this site's index is at /llms.txt, and each docs, guide and blog page comes as Markdown at its URL plus .md.

Headroom logo Headroom

Quickstart

Install Headroom, connect a coding agent, and verify that requests reach the local proxy.

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 desktop app: Claude Code sessions inside the Claude desktop app cannot be optimized. The app sets its own connection for those sessions and ignores the configuration Headroom writes. Run Claude Code in a terminal or in a supported IDE extension, such as VS Code, instead. Codex is not affected: its desktop app shares the CLI's configuration.

4. Verify routing

Check the connector status in Headroom first. To confirm the configuration Headroom wrote, search the agent's configuration file for the local proxy address.

macOS or Linux:

# Claude Code: expect "ANTHROPIC_BASE_URL": "http://127.0.0.1:6767"
grep ANTHROPIC_BASE_URL ~/.claude/settings.json
# ChatGPT Codex: expect lines with http://127.0.0.1:6767/v1
grep 127.0.0.1:6767 ~/.codex/config.toml

Windows PowerShell:

# Claude Code: expect "ANTHROPIC_BASE_URL": "http://127.0.0.1:6767"
Select-String ANTHROPIC_BASE_URL "$env:USERPROFILE\.claude\settings.json"
# ChatGPT Codex: expect lines with http://127.0.0.1:6767/v1
Select-String 127.0.0.1:6767 "$env:USERPROFILE\.codex\config.toml"

No output means the connector is not configured: turn it off and on in Headroom, then check again. On macOS and Linux, terminals opened while Headroom runs also get ANTHROPIC_BASE_URL and OPENAI_BASE_URL from your shell profile. Windows has no such export, so an empty $env:ANTHROPIC_BASE_URL there is expected and does not mean routing failed.

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

Install Headroom for your operating system.

Not ready to install yet?

Leave your email and we'll send a one-page summary of the benchmarks, plus a note when big updates ship. No drip campaign.