How to uninstall Headroom
Use the uninstall control inside Headroom to remove its managed integrations and local data.
Uninstall from the app
- Open Headroom from the menu bar or system tray.
- Open Settings using the gear icon.
- In the Uninstall section, click Uninstall Headroom.
- Review the items listed in the confirmation dialog. Click Uninstall and quit to run the cleanup.
- After Headroom exits, restart open terminals and coding-agent apps so they load the restored configuration.
Use this flow before removing the application with Finder, Homebrew, or a package manager. A normal Quit stops routing but retains Headroom's runtime and saved data for the next launch.
What the uninstall flow removes
- Headroom's managed agent routing, shell exports, and hooks, restoring previously saved connection settings.
- Headroom-installed add-ons and managed MCP server registrations.
- Headroom-owned runtime files, logs, caches, setup state, saved statistics, and credentials.
- Headroom's startup entry and managed configuration backups.
On macOS, the app schedules its application bundle to move to Trash after exiting. On Windows, it launches the installed Windows uninstaller. On Linux, run this cleanup first, then remove the installed package with your package manager or delete the AppImage.
The cleanup targets Headroom-managed files and integrations. It preserves unrelated agent configuration and shared third-party model caches. Review learned instructions in project files separately if you want those removed.
Verify removal
Start your coding agent in a new terminal or restart its desktop app. It should use its restored connection settings rather than Headroom's local proxy at 127.0.0.1:6767.
Existing terminals can retain ANTHROPIC_BASE_URL or OPENAI_BASE_URL from before removal. Restart them before diagnosing a remaining routing problem.
If you already deleted the app
Reinstall and open Headroom, then use Settings > Uninstall Headroom to run its cleanup. If the app cannot open or cleanup fails, contact support@extraheadroom.com with your operating system, app version, and error. Do not delete entire coding-agent configuration directories.
Separately installed CLI
A Headroom CLI you installed outside the desktop app's managed runtime is a separate installation. Remove it using the package manager and Python environment you used to install it, and remove any startup commands you added yourself.
Install Headroom for your operating system.