Troubleshooting

No requests or zero savings

1. Check that Headroom is running, setup has completed, and optimization is not paused.
2. Check that the intended agent connector is enabled.
3. Check the connector status and restart the agent. Inspect shell exports, where available, using the quickstart commands.
4. Start a new agent session and ask it to read a project file or run a test.
5. Check Activity for optimizations. Verify the request count separately with the agent runbook.

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. Claude Code inside the Claude desktop app cannot be optimized. 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 it fails again, send the error and app version to support.

No project learnings

1. Check that auto-learning is enabled in Optimize.
2. Confirm that requests reach Headroom and that you are inspecting the correct project.
3. Check the pending-pattern count in Auto-learning. For a manual scan, check the CLI prerequisites shown in Optimize, then use Scan now.

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, 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

Quit Headroom normally, restart Claude Code from a new terminal, and test Remote Control with the restored connection settings. Headroom will not optimize that session. Restart Headroom afterward to resume optimization.

Unsetting ANTHROPIC_BASE_URL in the shell alone is not a reliable bypass because Claude Code can also read the value from ~/.claude/settings.json. If the issue persists after quitting Headroom and restarting the client, investigate the client or account configuration.

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.

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.