# What Happens During Agent Reach Uninstallation and How to Preserve Your Configuration

> Learn what happens during Agent Reach uninstallation. Discover how to preserve your configuration using the --keep-config flag or preview changes safely with --dry-run.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-21

---

**The `agent-reach uninstall` command executes a deterministic cleanup that removes the `~/.agent-reach` configuration directory, skill registrations from supported hosts, and MCP entries, but you can preserve your credentials using the `--keep-config` flag or preview all changes safely with `--dry-run`.**

When you need to remove the Agent Reach toolkit from your system, the uninstallation process implemented in `Panniantong/Agent-Reach` follows a strict sequence defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to ensure complete cleanup while offering flexibility for configuration preservation. The routine handles everything from API credentials stored in [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) to skill registrations across multiple AI hosts, executing through a private helper function that coordinates four distinct removal phases.

## The Uninstallation Sequence in Agent Reach

According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), specifically within the `_cmd_uninstall` helper at line 1346, the uninstall routine proceeds through a deterministic sequence that handles dry-run checks, directory removal, skill cleanup, and MCP configuration purging.

### Step 1: Dry-Run Evaluation

If you provide the `--dry-run` flag, the command intercepts execution at lines 58–60 and prints projected changes without modifying the filesystem. This safety mechanism allows you to inspect every path that would be affected before any data is removed.

### Step 2: Configuration Directory Removal

By default, the hidden `~/.agent-reach` directory—which contains [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) with all tokens, cookies, and API keys—is deleted. The logic at lines 64–82 handles this removal unless the `--keep-config` flag is specified, in which case the `keep_config` guard skips this step entirely.

### Step 3: Skill File Cleanup

The command removes skill registrations from three supported hosts as implemented in lines 84–100:

- `~/.openclaw/skills/agent-reach` for OpenClaw
- `~/.claude/skills/agent-reach` for Claude Code  
- `~/.agents/skills/agent-reach` for generic agents

Symbolic links are unlinked while directories are recursively removed according to the filesystem type detected.

### Step 4: MCP Entry Purging

If the `mcporter` tool is present on the system, entries for built-in backends (`exa`, `xiaohongshu`) are purged from the MCP configuration. This logic resides at lines 106–124 of the CLI implementation.

### Step 5: Summary Report

Finally, the routine at lines 126–144 generates a summary indicating what was removed and suggests follow-up commands such as `pip uninstall agent-reach` or `npm uninstall -g mcporter` to complete the removal process.

## How to Preserve Configuration During Uninstallation

To retain your stored credentials while removing skill files and MCP entries, invoke the command with the `--keep-config` flag. This option prevents the deletion of the `~/.agent-reach` directory, ensuring your [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file remains intact with all cookies, API tokens, and proxy settings preserved.

```bash
agent-reach uninstall --keep-config

```

When this flag is active, the installer skips step 2 of the sequence (the configuration directory removal) while still executing the skill cleanup and MCP purging operations defined in the later steps.

## Previewing Changes with Dry-Run Mode

Before committing to any filesystem changes, use the `--dry-run` flag to inspect exactly what would be removed. As implemented at lines 58–60 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this mode prints each target path without executing deletions.

Example output includes:

```

[dry-run] Would remove config directory: /home/user/.agent-reach
[dry-run] Would remove OpenClaw skill: /home/user/.openclaw/skills/agent-reach
[dry-run] Would remove Claude Code skill: /home/user/.claude/skills/agent-reach

```

You can combine both flags to preview a configuration-preserving uninstall:

```bash
agent-reach uninstall --dry-run --keep-config

```

## Complete Command Reference

Execute a standard uninstallation that removes all components including credentials:

```bash
agent-reach uninstall

```

Preserve only your configuration while cleaning up skills and MCP entries:

```bash
agent-reach uninstall --keep-config

```

Preview the uninstallation without making changes:

```bash
agent-reach uninstall --dry-run

```

Perform a combined safety check while preserving configuration:

```bash
agent-reach uninstall --dry-run --keep-config

```

## Key Source Files

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Contains the `_cmd_uninstall` function at line 1346 and the flag handling logic for `--keep-config` and `--dry-run`
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)**: Manages the `~/.agent-reach/config.yaml` file structure and persistence
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Provides health-check utilities to verify system state before uninstallation

## Summary

- The `agent-reach uninstall` command in `Panniantong/Agent-Reach` executes a deterministic five-step cleanup process defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)
- By default, the command removes the `~/.agent-reach` directory containing all credentials, API keys, and configuration settings
- Use the `--keep-config` flag to preserve your [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) while removing skill registrations and MCP entries
- The `--dry-run` flag enables safe previewing of all changes at lines 58–60 before any filesystem modification occurs
- Skill cleanup targets three specific host directories: OpenClaw, Claude Code, and generic agents under `~/.agents/skills/`
- MCP entries for `exa` and `xiaohongshu` backends are purged if the `mcporter` tool is detected on the system

## Frequently Asked Questions

### Does Agent Reach uninstallation delete my API keys permanently?

Yes, unless you use the `--keep-config` flag. The default behavior removes the `~/.agent-reach` directory which contains your [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file with all stored tokens, cookies, and API keys as defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). To preserve these credentials, always run `agent-reach uninstall --keep-config` which skips the directory removal logic at lines 66–82 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

### What happens to my skill registrations when I uninstall Agent Reach?

The uninstaller removes skill registrations from three supported hosts: OpenClaw (`~/.openclaw/skills/agent-reach`), Claude Code (`~/.claude/skills/agent-reach`), and generic agents (`~/.agents/skills/agent-reach`). According to the implementation at lines 84–100 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), symbolic links are unlinked while directories are deleted recursively, ensuring no orphaned skill references remain.

### Can I preview what will be deleted before running the uninstall command?

Yes, use the `--dry-run` flag. This mode, implemented at lines 58–60 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), prints all paths that would be removed without making any filesystem changes. You can combine it with `--keep-config` to verify exactly what will remain on your system, allowing you to confirm that your configuration directory will be preserved before executing the actual deletion.

### Where is the uninstallation logic implemented in the Agent Reach source code?

The uninstallation logic resides in the `_cmd_uninstall` function at line 1346 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). This function coordinates the dry-run checks at lines 58–60, configuration removal guarded by lines 66–82, skill cleanup at lines 84–100, and MCP entry purging at lines 106–124. Related configuration handling is managed in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which defines the structure of the `~/.agent-reach` directory.