Headroom

How to uninstall Headroom

No dark patterns here: the complete removal is two steps, and this page lists every leftover so you can do a clean sweep if you want one. There is also a short section on the handful of problems people uninstall over, in case yours has a fix that takes less time than reinstalling later.

The two-step uninstall

  1. Quit Headroom from the menu bar. Click the Headroom icon and choose Quit. This is what actually unwires it: quitting reverts the ANTHROPIC_BASE_URL routing variable, removes the managed blocks it added to your shell configuration, and removes the hooks it installed.
  2. Drag the app to the Trash. Open Applications, drag Headroom.app to the Trash, empty it.

If you installed via Homebrew, brew uninstall --cask headroom covers both steps, because the cask's quit action runs the same teardown before removing the app.

Will this break Claude Code or Codex?

No. Headroom never modifies Claude Code or Codex themselves — it routes them through a local proxy by setting a base URL and a few clearly marked configuration blocks. Quitting reverts all of it. Open a new terminal after quitting and your agents behave exactly as they did before you installed anything.

If a terminal that was already open still points at the proxy, that shell just has a stale environment. Open a new one, or run ANTHROPIC_BASE_URL= claude for that session.

Leftovers worth deleting

Dragging the app to the Trash leaves a few items behind. None of them affect your agents or run anything, so you can ignore them safely — but if you want nothing left, here they are:

  • Application support folder. ~/Library/Application Support/Headroom/ holds the local runtime, logs, config, and your saved savings stats.
  • Legacy log directory. ~/.headroom/, if it exists from an older install.
  • MCP server entry. Headroom registers an MCP entry for content retrieval in your agent config (~/.claude.json for Claude Code, ~/.codex/config.toml for Codex). Remove the Headroom entry if you are tidying those files by hand.
  • Backup files. Headroom writes a .bak copy next to any config file it edits, so you can always see what it changed. Delete them once you are satisfied the originals are correct.
  • Keychain item. A single entry storing your account credential. Search for "Headroom" in Keychain Access and delete it.

Uninstalling the open-source CLI

If you installed the Headroom CLI yourself rather than the app, that is a separate install: pip uninstall headroom-ai, plus removing any headroom wrap or headroom proxy lines you added to your own shell configuration or scripts. The app does not touch that install and uninstalling one does not remove the other.

Before you go: the usual reasons

If one of these is why you are here, it may be quicker to fix than to leave.

  • Remote Control disappeared from Claude Code. This one is real and not fixable from our side: since Claude Code 2.1.196, Anthropic hides /remote-control whenever ANTHROPIC_BASE_URL points anywhere other than their API, which is how Headroom routes traffic. For a single session, run ANTHROPIC_BASE_URL= claude. Quitting Headroom restores it entirely.
  • It does not work with the Claude desktop app. Also true. Headroom works with the Claude Code CLI and its IDE extensions, but the Claude desktop app does not route through a local proxy, so there is nothing to optimize there.
  • The savings look smaller than expected. Savings track how much compressible bulk your sessions actually contain. Short conversational sessions have little to trim; sessions heavy on file reads, logs, search output, and long documents have a lot. The activity view breaks this down per session, which is usually more informative than the headline number.
  • You are on Windows or Linux. The app is macOS only today. The open-source CLI is cross-platform and does the same compression.

Something else? The FAQ covers privacy, prompt caching, latency, and quality benchmarks in more detail.

Reinstalling later

Nothing is stopping you. Reinstalling picks up where you left off if the application support folder is still there, and starts clean if you deleted it. Your account and any remaining trial or subscription time are tied to your email, not the machine.