How to Uninstall Headroom (and What to Use Instead)

To uninstall Headroom, undo each thing it set up, in this order, while the headroom command still exists: remove any persistent deployment, unwrap every agent, remove the MCP server, then delete the package and its data. There is no single headroom uninstall command yet.

Order matters because the CLI does the restoring. Delete the package first and you are left editing agent configs by hand.

Headroom's own documentation says it plainly: "A full teardown currently spans several commands" and is tracked in issue #748, which proposes a consolidated headroom uninstall. That issue was still open when I checked.

Steps taken from Headroom's README and its docs at docs.headroomlabs.ai, read on 2026-10-15. Commands can change between releases, so check headroom --help on your version.

What does Headroom install on your machine?

Up to six kinds of change, depending on which commands you ran. List yours before you start, because each one has its own removal step.

Two extras are easy to forget. headroom learn writes corrections to CLAUDE.local.md by default, or to CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md. And the Docker install script puts a headroom wrapper in ~/.local/bin or ~/bin and edits your shell startup files.

Step 1: Remove any persistent deployment

If you ever ran headroom deploy or headroom install apply, run headroom install remove first. Check with headroom install status.

Per the docs, the final install remove restores the original snapshot of the agent configs it edited and deletes its backup files. It is the lifecycle command for the deployment profile behind the service, scheduled watchdog or Docker container that kept the proxy alive. If you only ever ran headroom proxy in a terminal, stop it with Ctrl+C and skip this step.

Step 2: Unwrap every agent you wrapped

Run headroom unwrap <tool> once per agent. Each wrap is undone separately, so you need to remember which agents you wrapped.

The README lists claude, copilot, codex, grok, kimi, omp, opencode, openclaw and zcode. The docs add vscode-claude and vscode for the VS Code integrations, and grok-build. Per the docs, unwrap restores the pre-wrap config from a backup where one exists, and removes the Serena registration that wrap added.

Do this before Step 4. The docs warn that in VS Code, while the proxy is stopped, requests "fail closed" instead of bypassing Headroom. Unwrapping is what restores direct access.

Step 3: Remove the MCP server

Run headroom mcp uninstall. It is a separate registration from wrap, made by headroom mcp install.

Then list your MCP servers (for Claude Code, claude mcp list) and confirm no headroom entry remains. If you kept Serena on purpose, leave it.

Step 4: Remove the package

Uninstall the package the way you installed it. The CLI only ships in the PyPI package headroom-ai.

If you installed the npm package globally, add -g; issue #748 names the global npm package as the one people miss. If you used the Docker install script instead, remove the headroom wrapper from ~/.local/bin or ~/bin, delete the PATH block it added to your shell startup files, and remove the image with docker rmi ghcr.io/headroomlabs-ai/headroom:latest. The docs describe what that installer adds; they don't document a removal command for it.

Step 5: Clean up data and environment variables

Delete ~/.headroom once you're sure you don't need its savings history. This cannot be undone.

Then look for anything you set by hand. If you followed the proxy instructions, you may have exported ANTHROPIC_BASE_URL=http://localhost:8787 or OPENAI_BASE_URL in your shell profile, plus HEADROOM_* variables. Remove those lines and open a new terminal. Finally, review CLAUDE.local.md, CLAUDE.md or AGENTS.md for corrections headroom learn wrote, and keep only what you still want.

How do you check that nothing is left?

Run these checks; each should print nothing.

Also check your shell startup files for a Headroom PATH block, and for leftover *.headroom-backup files next to agent configs. A backup that survived means that agent's restore didn't run, so compare it with the live file before deleting anything.

One sign it worked: Claude Code's /remote-control comes back. Headroom's docs note it disappears when ANTHROPIC_BASE_URL points at a host other than api.anthropic.com.

Why people remove Headroom

Mostly because it didn't make sessions cheaper. On the open THOL benchmark, Headroom made long sessions 52.8% more expensive than the same agent with no tool, a gap outside the run-to-run noise: measurably more expensive.

Disclosure: I maintain THOL and I build Tokenade. The benchmark is public and reproducible, but it is not an independent third party. How it works is on the THOL explainer.

The per-message compression works; THOL measures the bill, not the cause. In a real agent loop, anything that makes the agent take extra steps costs more than it saves, because every extra step re-sends the whole history.

What to use instead: Tokenade

Tokenade is the replacement measured to lower the bill: on long sessions it makes a session 39% cheaper than the agent on its own. It works at the other end of the pipe: it trims what tools return (command output, file reads, MCP results) before it reaches the model, instead of rewriting every message.

Install takes two commands:

tokenade install detects your agents and wires their hooks, so by default there is no proxy and no base URL to change. An optional local LLM proxy exists for agents hooks can't reach; it also starts at port 8787, so run the checks above before enabling it. Compaction runs on your machine. The full guide is on the install docs.

The teardown is one command, for the record: tokenade uninstall, and tokenade uninstall --dry-run lists what it would remove first. Tokenade is free and open source (MIT/Apache-2.0).

If you'd rather compare first, Headroom alternatives ranks six options on the same criteria, and Tokenade vs Headroom puts the two side by side.

FAQ

Is there a headroom uninstall command?

Not yet. Headroom's docs say a full teardown spans several commands and point to issue #748, which proposes one consolidated headroom uninstall. Until it ships, use install remove, unwrap, mcp uninstall and your package manager, in that order.

Does pip uninstall headroom-ai remove everything?

No. It removes the CLI, but not the agent configs wrap edited, the MCP registration, a persistent service or container, or ~/.headroom. Worse, once the CLI is gone you can no longer run headroom unwrap, so do Steps 1 to 3 first.

Claude Code stopped working after I removed Headroom. Why?

Something still points it at the proxy on port 8787. Look for ANTHROPIC_BASE_URL in your environment, your shell profile and the env block of ~/.claude/settings.json. If the CLI is still installed, headroom unwrap claude (or vscode-claude) restores the previous values.

How do I remove Headroom from VS Code?

Run headroom unwrap vscode-claude for the Claude Code extension and headroom unwrap vscode for Copilot. If you passed --settings-file during setup, pass the same option when unwrapping. Other VS Code settings are preserved, per the docs.

Should I delete ~/.headroom?

Yes, if you're done with Headroom. It holds config, logs, savings stats and its local compression store. Copy anything you want to keep first; deletion is permanent.

See also:

• Headroom alternatives — six options, ranked on measured session cost
• Tokenade vs Headroom — the two side by side
• headroom vs rtk — whole-message compression against shell filtering
• Best Claude Code token optimizers — the full field, same methodology
• Install Tokenade — three commands