> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guardway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Uninstall & Recovery

> Remove the Guardway agent safely, and get Claude Code working again if it stops responding after an agent change.

## What this is for

The macOS `.pkg` installs the agent in **managed mode**: Claude Code's enterprise
`managed-settings.json` is pointed at a local tap, so every session on the machine is metered and
policy is applied. Managed settings override user and project settings, which is what makes the
policy enforceable — and it means the wiring **outlives the agent**.

That matters when removing it. If the tap stops while the settings still point at it, every Claude
Code session on the machine dials a port nothing answers.

<Warning>
  **Never delete `gw-cli` by hand.** Unwire Claude Code first. The uninstaller does this in the
  right order automatically; deleting the binary first removes the tool that knows how to undo the
  wiring.
</Warning>

## Claude Code stopped working — fix it first

If Claude Code hangs or fails to reach the API after an agent change, run this. It un-wires Claude
Code and **leaves the agent installed**:

```sh theme={null}
sudo gw-cli uninstall --repair
```

If `gw-cli` itself is gone or won't run, the standalone uninstaller does the same thing and needs
no Guardway tooling:

```sh theme={null}
sudo /usr/local/bin/guardway-uninstall --repair
```

And if both are missing, deleting the managed settings file is enough on its own:

```sh theme={null}
sudo rm "/Library/Application Support/ClaudeCode/managed-settings.json"
```

<Info>
  These three are the same fix at decreasing levels of tooling. The last one always works, because
  it depends on nothing but the file being there.
</Info>

## Full uninstall

```sh theme={null}
sudo gw-cli uninstall
```

Removes the agent completely: the tap daemon, the menu-bar app, both data directories, logs, the
package receipt, and the binaries. Requires `sudo`.

<ParamField path="--repair">
  Un-wire Claude Code and stop there. The agent stays installed and running. Use this when Claude
  Code is broken but you are not trying to remove the product.
</ParamField>

<ParamField path="--dry-run">
  Print every action and change nothing. Safe to run at any time.
</ParamField>

<ParamField path="--keep-data">
  Keep scan history, logs, and the data directories.
</ParamField>

<ParamField path="--keep-policy">
  Leave org policy controls (skill lockdown, permissions, sandbox) in the harness settings. Note
  that this can leave Claude Code restricted to the organisation's sanctioned skill list after the
  agent is gone — the command tells you when it does.
</ParamField>

```sh theme={null}
sudo gw-cli uninstall --dry-run    # see what would happen
sudo gw-cli uninstall --repair     # un-wire only, keep the agent
sudo gw-cli uninstall              # remove everything
```

<Note>
  `gw-cli uninstall` is a thin wrapper — it runs `/usr/local/bin/guardway-uninstall`, which is
  installed by the `.pkg`. Both accept the same flags and behave identically. The script is
  deliberately standalone (plain `bash`, no Rust, no network) so it still works when the agent is
  already broken or removed.
</Note>

## Restart open Claude Code sessions

Claude Code reads these settings **at launch**. Sessions already running when you make the change
keep the old configuration, and a stranded session **hangs rather than reporting an error** — so
nothing on screen explains it.

The uninstaller lists them for you:

```
! 9 Claude Code session(s) started before this change
    PIDs: 2165 2172 2180 2188 2194 5310 37633 44446 45082
    The tap is gone, so these MAY already be stranded — a stranded session HANGS
    rather than erroring, so nothing on screen explains it. Kill and relaunch them.
    Sessions started after this run are fine.
```

Kill and relaunch anything listed. After `--repair` the behaviour differs: because the agent is
left running, those sessions keep working **for now** and fail the next time the tap stops — a
reboot, an upgrade, or a later uninstall. Restart them when convenient rather than urgently.

## What the uninstaller guarantees

A failed uninstall must never take Claude Code down. The order is fixed and enforced:

<Steps>
  <Step title="Un-wire Claude Code — first, before anything is stopped">
    Removes the base URL, the telemetry export, the policy hooks, and org policy controls from
    every tier: managed settings, each user's `~/.claude`, VS Code, and Cursor. Values Guardway did
    not write are left alone; a file it empties is deleted.
  </Step>

  <Step title="Verify from disk">
    Re-reads the files and confirms nothing remains. **If verification fails, the run stops here
    and removes nothing else** — the tap is left running and Claude Code keeps working. Exit
    code `2`.
  </Step>

  <Step title="Stop services">
    Boots out the tap daemon and the menu-bar app, then removes their launchd entries.
  </Step>

  <Step title="Remove the app, data, logs and package receipt">
    Timestamped backups of every settings file it edited are kept (the three most recent per file).
  </Step>

  <Step title="Remove the binaries — last">
    `gw-cli` and the uninstaller are the recovery tools right up until the moment they are provably
    no longer needed.
  </Step>
</Steps>

## Recovery notes on the machine

A managed install leaves a plain-text file next to the settings it writes:

```
/Library/Application Support/ClaudeCode/GUARDWAY-RECOVERY.txt
```

It names what is wired and carries the same three fixes as this page, including the one that needs
no Guardway tooling. It is there for whoever is debugging a broken Claude Code without this
documentation to hand.

## Other platforms

<Warning>
  `gw-cli uninstall` is macOS-only today.
</Warning>

| Platform    | Removal                                                                                |
| ----------- | -------------------------------------------------------------------------------------- |
| **Linux**   | `packaging/install-service.sh --remove`, then delete `~/.guardway`                     |
| **Windows** | `gw-cli autostart --remove`, then uninstall from **Apps & features** (or `msiexec /x`) |

Neither platform runs the managed in-path mode, so neither has the base-URL hazard this page is
mostly about.

## Related

* [CLI Reference](/discovery/guardway-cli/cli-reference) — every command and flag
* [Overview](/discovery/guardway-cli/overview) — install and first run