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 extension in VS Code, Cursor, Windsurf 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. |
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. See Headroom for OpenCode. |
| Grok Build | Yes (beta) | Turn on the Grok Build connector. |
| Pi | Manual setup | See Pi. |
| 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. |
| Cursor's and Windsurf's built-in agents and models (including Devin) | No | Install the Claude Code or Codex extension inside the editor and use that. |
| ChatGPT chat mode, Claude.ai in the browser, 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.
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.