# How to Uninstall Headroom (and What to Use Instead)

> Headroom has no one-line uninstall. Here is the order that works, from its own docs: unwrap, remove the MCP server and persistent proxy, delete the package and data, then verify.

Source: https://tokenade.net/en/articles/uninstall-headroom · Updated: 2026-10-25

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](https://github.com/headroomlabs-ai/headroom/issues/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.

| What | Where it lives | Created by |
|------|----------------|-----------|
| The `headroom` CLI | A uv tool environment or a pip install of `headroom-ai` | `uv tool install` or `pip install` |
| The TypeScript SDK | `headroom-ai` in a project's `node_modules` (no CLI) | `npm install headroom-ai` |
| A local proxy on port 8787 | A running process, Docker container, service or scheduled task | `headroom proxy`, `headroom wrap`, `headroom deploy`, `headroom install apply` |
| Agent wiring | Agent config files, sometimes `CLAUDE.md` or `AGENTS.md`, MCP entries including Serena in `~/.claude.json` | `headroom wrap <tool>` |
| Persistent routing | `~/.claude/settings.json` `env`, a managed block in `~/.codex/config.toml` or `~/.config/opencode/opencode.json` | `headroom deploy`, `headroom install apply` |
| Data and logs | `~/.headroom` (config, logs, savings stats, `ccr_store.db`, deployment manifests) | Every mode |

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`.

```sh
headroom install status
headroom install stop
headroom install remove
```

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.

```sh
headroom unwrap claude
headroom unwrap codex
headroom unwrap opencode
```

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`.

```sh
headroom mcp uninstall
```

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`.

```sh
uv tool uninstall headroom-ai     # if installed with uv tool install
pip uninstall headroom-ai         # if installed with pip
npm uninstall headroom-ai         # the TypeScript SDK, inside your project
```

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.

```sh
rm -rf ~/.headroom
```

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.**

```sh
command -v headroom
env | grep -i -E 'headroom|8787'
grep -n -E 'headroom|8787' ~/.claude/settings.json ~/.claude.json ~/.codex/config.toml ~/.config/opencode/opencode.json 2>/dev/null
lsof -i :8787
docker ps -a | grep headroom
ls ~/.headroom 2>/dev/null
```

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](https://tokenade.net/en/thol).

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:

```sh
npm install -g @tokenade/cli
tokenade install
```

`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](https://tokenade.net/en/docs/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](https://tokenade.net/en/docs/install).

> Nothing to unwrap: Tokenade plugs into your agent's hooks and trims what it reads, and one command removes it.
>
> Install: `npm install -g @tokenade/cli && tokenade install` — or let your agent do it: https://tokenade.net/install.md

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](https://tokenade.net/en/comparisons/alternatives/headroom-alternatives) ranks six options on the same criteria, and [Tokenade vs Headroom](https://tokenade.net/en/comparisons/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](https://tokenade.net/en/comparisons/alternatives/headroom-alternatives) — six options, ranked on measured session cost
- [Tokenade vs Headroom](https://tokenade.net/en/comparisons/tokenade-vs-headroom) — the two side by side
- [headroom vs rtk](https://tokenade.net/en/articles/headroom-vs-rtk) — whole-message compression against shell filtering
- [Best Claude Code token optimizers](https://tokenade.net/en/articles/best-claude-code-token-optimizers) — the full field, same methodology
- [Install Tokenade](https://tokenade.net/en/docs/install) — three commands