Which apps and agents Headroom works with
Headroom works with coding agents that run on your own computer and send their requests through a local address it can set. It cannot reach apps that talk to the model provider from their own servers or ignore that setting.
Compatibility table
| App or agent | Works? | How |
|---|---|---|
| Claude Code in any terminal on your computer | Yes | Turn on the Claude Code connector, then open a new terminal. |
| Claude Code with Kimi, GLM, MiniMax or DeepSeek models | Yes | Choose the provider under Settings > Claude Code provider in Headroom. |
| Claude Code extension in VS Code, Cursor, Windsurf, Antigravity or JetBrains | Yes | Turn on the Claude Code connector, then quit and reopen the editor. See Cursor. |
| ChatGPT Codex: CLI, IDE extension, and Codex mode in the ChatGPT desktop app | Yes | Turn on the Codex connector, then restart the app or terminal. Works on every ChatGPT plan, including Business. |
| Claude Code Remote Control | Per session, without Headroom | Type /remote-control in a terminal or /remote-control-headroom in the VS Code panel. Headroom restarts that session without itself. See Remote Control. |
Agent runners that start Claude Code or Codex for you (Conductor, bb, claude -p scripts) | Yes | Nothing extra. They inherit the connector's routing. |
| OpenCode | Yes (beta) | Turn on the OpenCode connector. It works with any provider you use in OpenCode, and OpenCode 2 needs Headroom 0.9.50 or newer. See Headroom for OpenCode. |
| Grok Build | Yes (beta) | Turn on the Grok Build connector. |
| Pi | Manual setup | See Pi. |
| Claude Code on a remote server over SSH | Manual setup | See remote servers. |
| Cline, Roo Code, Aider and other tools that call the model API themselves | Sometimes | Only if the tool has its own base URL setting. See other tools. |
| Claude desktop app: Chat, Cowork and the Code tab | No | The app does not use the routing setting Headroom relies on. Run Claude Code in a terminal or VS Code on the same project instead. Add-ons such as Ponytail, MarkItDown and Serena still work in its Code tab. |
| The built-in agents and models of Cursor, Windsurf (including Devin) and Antigravity | No | Install the Claude Code or Codex extension inside the editor and use that. |
| GitHub Copilot | No | It has no setting that sends its requests through Headroom. Install the Claude Code or Codex extension in VS Code and use that. |
| Gemini CLI and the Gemini app | Not yet | There is no Gemini connector yet. Tell support if you want one. |
| ChatGPT chat mode, Claude.ai in the browser, the Grok app, Perplexity | No | These run on the provider's servers, not through your computer. |
| Cloud agents and shells (Replit, Claude Code on the web) | No | Clone the project to your computer and run the agent locally. |
Cursor (and other VS Code forks)
Cursor's own models are not routed. The Claude Code and Codex extensions inside Cursor are, because they are the same extensions as in VS Code.
- In Cursor, open Extensions (Cmd+Shift+X, or Ctrl+Shift+X on Windows) and install Claude Code for VS Code by Anthropic and/or Codex by OpenAI.
- In Headroom, turn on the Claude Code and/or Codex connector.
- Quit Cursor completely and reopen it so the extensions pick up the new settings.
- Open the Claude or Codex panel, sign in, and send a message. The request appears in Headroom's Activity.
Pi
Headroom does not set up Pi automatically. Pi lets you point its built-in providers at another address, so you can route it by hand. Add the entries for the accounts you use to ~/.pi/agent/models.json:
{
"providers": {
"anthropic": { "baseUrl": "http://127.0.0.1:6767" },
"openai": { "baseUrl": "http://127.0.0.1:6767/v1" },
"openai-codex": { "baseUrl": "http://127.0.0.1:6767/backend-api" }
}
}
anthropic: an Anthropic API key or a Claude Pro or Max login.openai: an OpenAI API key only. Do not use it with a ChatGPT sign-in.openai-codex: a ChatGPT Plus or Pro subscription (Pi's Codex login). This one is the least tested.
Restart Pi, or reopen /model. Headroom does not undo a manual setup when it quits, so Pi fails to connect while Headroom is not running. Remove these lines before you uninstall Headroom. Tell support how it goes; it decides whether Pi gets a connector.
Remote servers over SSH
Claude Code on a server you SSH into can use Headroom on your own computer:
- On your computer, add this line under the server's
Hostentry in~/.ssh/config:RemoteForward 6767 127.0.0.1:6767 - On the server, add this to
~/.claude/settings.json, or merge it into theenvblock you already have:{"env":{"ANTHROPIC_BASE_URL":"http://127.0.0.1:6767","ENABLE_TOOL_SEARCH":"true"}} - SSH in again and start
claude. Its requests go through Headroom on your computer and show up in the app as usual.
Claude Code on the server only connects while you are logged in over SSH and Headroom is running on your computer. A session left running in tmux loses its connection when you disconnect, until you reconnect.
Other tools
A tool that calls the model API with its own HTTP client never reads Claude Code's or Codex's settings. If it has a base URL setting, point it at http://127.0.0.1:6767 for Anthropic models or http://127.0.0.1:6767/v1 for OpenAI models. Like the Pi setup, this is manual: undo it if you stop running Headroom.
When Headroom is not running
When you quit Headroom, it switches your connected agents back to connecting directly, and switches them to Headroom again on the next launch. From version 0.9.29 it does the same when Headroom closes unexpectedly. Start a new agent session afterward: a session that was already open may keep using Headroom's address and fail with Connection refused (ECONNREFUSED). In earlier versions an unexpected close leaves your agents pointed at Headroom with that error until you reopen it. If Headroom keeps closing on its own, email support with the address you signed up with.
A manual setup, such as Pi or a base URL you set in another tool, is never switched back. It fails while Headroom is not running.
Install Headroom for your operating system.