Troubleshooting
Find the symptom below, run the checks, and verify the result in a new agent session.
No requests or zero savings
Using Claude Code in the Claude desktop app? Those sessions cannot be optimized, whatever the connector status shows: the app sets its own connection and ignores Headroom's configuration. Run Claude Code in a terminal or a supported IDE extension, such as VS Code. See Connect your coding agent.
- Check that Headroom is running, setup has completed, and it is not paused: when it is, its menu bar or tray icon menu shows Resume Headroom. On Windows the icon can hide under the ^ next to the clock.
- Check that the intended agent connector is enabled.
- Close and reopen the terminal, editor or ChatGPT app. One that was open before Headroom keeps connecting directly. Turn on Open on login in Settings so Headroom always starts first.
- In Claude Code, run
/status: it should show the Anthropic base URLhttp://127.0.0.1:6767. Or check the agent's configuration file with the quickstart commands. - Start a new agent session and ask it to read a project file or run a test.
- Check Activity for optimizations. Verify the request count separately with the agent runbook.
On Home, Connected, no requests yet means nothing has gone through Headroom so far. Ran without Headroom means your agent ran a session that bypassed it; hover the badge to see why.
Requests recorded, but no savings: the traffic may contain little compressible content. A zero savings value does not by itself indicate a routing failure.
No requests recorded: check whether that client supports the configured proxy. The Claude Code CLI and its supported IDE extensions use different configuration. A tool that calls the model API directly with its own HTTP client, rather than launching the agent CLI, never reads that configuration and cannot be routed; see which IDEs and agent runners work.
Initial setup does not finish
First launch downloads the managed runtime and compression model. Leave the app open while downloads are progressing.
If setup reports a failure, check the error, available disk space, and whether your network permits the download. Retry after addressing the reported cause. If a company firewall blocks the download, finish the first setup on another network, such as a phone hotspot. If it fails again, send the error and app version to support.
On Windows, security software is the usual cause, and the error says which:
- Smart App Control blocks Headroom's runtime. Open Windows Security > App & browser control > Smart App Control settings, turn it off, then click Retry.
- Antivirus removes a file Headroom just downloaded. Check Virus & threat protection > Protection history, add
%LOCALAPPDATA%\Headroomas an exclusion, then click Retry. From version 0.9.50, Headroom downloads a fresh copy of a removed runtime file on its own.
The sign-in code does not arrive
The code comes from hello@extraheadroom.com and expires after 15 minutes. Check spam, and on a work account check quarantine: Microsoft 365 often holds the email there. Then request a new code in Headroom.
You paid, but Headroom says your trial ended
Headroom is usually signed in with a different email from the one you paid or redeemed your AppSumo code with. Open Settings, click Sign out, and sign in with the purchase email. Then quit Headroom from its menu bar or tray icon and open it again. If your plan still does not show, contact support with both addresses.
Errors that an update fixes
These errors came from bugs in older versions of Headroom. If you see one, update Headroom, then start a new session.
| Where | Error or symptom | Fixed in |
|---|---|---|
| Claude Code | "Server disconnected without sending a response", or a 502 on long replies behind a VPN, proxy or antivirus | 0.9.39 |
| Claude Code | "No such tool available: headroom_retrieve" | 0.9.40 |
| Codex | "stream disconnected before completion: stream closed before response.completed", or a long session that stops answering after a web search | 0.9.38 |
| Codex on Windows | Stuck on "Reconnecting" up to 5/5 | 0.9.41 |
| ChatGPT desktop app | Dots, dictation, voice, image generation or read-aloud missing | 0.9.48 |
| OpenCode 2 | "configured plugin path must be a directory" | 0.9.50 |
If an error persists on the newest version, check status.claude.com or status.openai.com, then contact support.
Turn Headroom off for a while
Choose Pause Headroom from its menu bar or tray icon. Your coding tools connect directly until you choose Resume Headroom. Restart sessions you started during the pause so they go through Headroom again.
For a single Claude Code session without optimization, start it with:
ANTHROPIC_CUSTOM_HEADERS="x-headroom-bypass: true" claude
No project learnings
- Check that auto-learning is enabled in Optimize.
- Confirm that requests reach Headroom and that you are inspecting the correct project.
- Check the pending-pattern count in Auto-learning. For a manual scan, check the CLI prerequisites shown in Optimize, then use Scan now.
- If the scan reports that Claude Code or Codex is not signed in, open a terminal, run
claudeorcodex, sign in, then scan again. The scan runs the command-line tool, which has its own sign-in: signing in to the Claude desktop app does not sign in theclaudeCLI.
No eligible patterns can be a valid result. If the scan reports an error or repeatedly fails to complete, record that error for support. See project learnings for the expected behavior.
An add-on does not install or appear
Check the error beside the add-on in Headroom. Confirm its prerequisites in the add-on reference: most need the Claude Code or Codex CLI, Node.js and Git, which on Windows is Git for Windows. Install what is missing, quit and reopen Headroom, then retry installation.
Start a new agent session after enabling it. An existing session may retain its previous tools or instructions. Ask the agent to use the add-on for a relevant task and inspect its tool calls or response.
Claude Code Remote Control is unavailable
Claude Code turns off Remote Control whenever ANTHROPIC_BASE_URL points anywhere other than api.anthropic.com. Claude Code makes that check itself, so a session routed through Headroom cannot use Remote Control. Headroom adds a command that restarts the session without Headroom, so Remote Control works there:
- Terminal: type
/remote-control. Headroom's command replaces Claude Code's, asks you to confirm, then ends the session and resumes the same conversation with Remote Control on. - VS Code panel: type
/remote-control-headroom. The panel keeps/remote-controland/rcfor its own toggle, which hits the same check. The panel stays open and adds a line to the conversation once Remote Control is active.
The restart takes up to 30 seconds. Headroom does not optimize the restarted session, and its first request resends the conversation without the prompt cache. Other sessions keep running through Headroom.
The terminal command works on macOS and Linux. The panel restart works on macOS, and on Linux and Windows from Headroom 0.9.34. Windows has no terminal command: quit Headroom, start Claude Code from a new terminal, and restart Headroom when you are done.
If the command says Headroom cannot restart the session (an alias for claude, a terminal opened before Headroom set up Claude Code, or an editor without Headroom's wrapper), exit the session and run the command it prints. It resumes the same session with Remote Control on.
Unsetting ANTHROPIC_BASE_URL in the shell alone does not work, because Claude Code also reads the value from ~/.claude/settings.json.
On Windows, if application control blocks Headroom's VS Code process wrapper, set "claudeCode.claudeProcessWrapper": "" in VS Code's user settings.json. An explicit empty value keeps the wrapper off when Headroom repairs its setup. Headroom's Claude Code proxy settings remain in place. The automatic Remote Control restart from the VS Code panel will not work with the wrapper off.
Connections to Headroom keep getting cut
The status keeps switching between running and "runtime offline" or "proxy unreachable", or the app says something on this computer is cutting your coding tools' connections. Headroom itself is usually fine: software between your tools and Headroom drops the connections. Check these causes in order, and restart Headroom after each change.
- AdGuard for Windows. Open AdGuard, go to Settings > Network, and change the network driver from WFP (the default) to SockFilter. Excluding Headroom from filtering does not fix it. Turning AdGuard for Windows off also works. AdGuard Home on a router or network gateway only filters DNS and does not cause this.
- Antivirus or security suites with web or traffic protection. Pause web protection briefly to test. If that helps, exclude
headroom-desktop.exeand127.0.0.1from it. - A VPN, firewall or corporate proxy that intercepts local traffic. Disconnect it briefly to test.
- A second copy of Headroom. Quit Headroom, end any remaining
headroom-desktop.exein Task Manager (or Activity Monitor on macOS), then start it again.
To check the connection yourself, run this in Command Prompt on Windows:
curl.exe -s -m 5 -o NUL -w "%{http_code}\n" http://127.0.0.1:6767/readyz
On macOS or Linux, in a terminal:
curl -s -m 5 -o /dev/null -w "%{http_code}\n" http://127.0.0.1:6767/readyz
200 means the connection works. 000 means it was cut. Run it a few times, since the drops are intermittent. If none of the above helps, contact support and mention which security software, VPN or network tools you run.
Port already in use
The default proxy uses port 6767; the optimization backend defaults to 6768 and can select another available port. Check which process owns the port reported in the error.
On macOS or Linux:
lsof -nP -iTCP:6767 -sTCP:LISTEN
In Windows PowerShell:
Get-NetTCPConnection -LocalPort 6767 -State Listen
Quit an unintended duplicate app or resolve the other application's port configuration, then relaunch Headroom. Identify the process before stopping it. Until the port is free, Headroom points your coding tools straight at their provider, so they keep working without optimization.
On Windows, WinError 10013 means Windows refused the port: security software filtering local connections, or a port range reserved by Hyper-V, WSL2 or Docker. Allow Headroom in your antivirus or firewall's network protection, list the reserved ranges in PowerShell, then click Retry:
netsh int ipv4 show excludedportrange protocol=tcp
Contact support
Email support@extraheadroom.com with:
- Your operating system, Headroom version, and coding-agent version.
- The steps that reproduce the problem and the exact error message.
- Whether requests appear in Activity and approximately when the issue occurred, including your time zone.
Remove credentials and private project content from any logs you share. For removal instructions, see uninstall.
Install Headroom for your operating system.