# Agent Reach Uninstall Process: Complete Guide to Removing Components and Data

> Master the Agent Reach uninstall process. This guide details component and data removal, including configuration directories and skill registrations. Safely uninstall Agent Reach with our expert steps.

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

---

**The Agent Reach uninstall process removes the configuration directory (`~/.agent-reach`), skill registrations from OpenClaw, Claude Code, and Agent runtimes, and mcporter MCP entries, with optional `--dry-run` and `--keep-config` flags for safety.**

The Agent Reach uninstall process provides a complete cleanup mechanism for the Panniantong/Agent-Reach Python CLI tool. When you execute `agent-reach uninstall`, the `_cmd_uninstall` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) systematically purges all persistent data created during installation. This ensures no tokens, cookies, or skill registrations remain on your system while giving you full control over what gets deleted.

## Components Removed During the Agent Reach Uninstall Process

The uninstaller targets four distinct categories of persisted data. Each removal step respects the `--dry-run` flag, which reports what *would* be removed without touching the filesystem.

### Configuration Directory and Credentials

The uninstaller removes the **configuration directory** at `~/.agent-reach`, which stores sensitive data including [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) with tokens, cookies, and API keys. This directory is created by the installer and managed through [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

As implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1394-1404):

```python
config_dir = os.path.expanduser("~/.agent-reach")
if not keep_config:
    if os.path.isdir(config_dir):
        if dry_run:
            print(f"[dry-run] Would remove config directory: {config_dir}")
        else:
            shutil.rmtree(config_dir)

```

Pass `--keep-config` to preserve this directory while removing other components.

### Skill Registration Directories

Agent Reach registers itself as a skill for multiple AI agent runtimes. The uninstaller removes the entire skill directories containing [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) and `references/` files from three locations:

- `~/.openclaw/skills/agent-reach` (OpenClaw runtime)
- `~/.claude/skills/agent-reach` (Claude Code runtime)
- `~/.agents/skills/agent-reach` (generic Agent runtime)

The code handles both symlinks and regular directories (lines 1412-1430):

```python
skill_dirs = [
    ("~/.openclaw/skills/agent-reach", "OpenClaw"),
    ("~/.claude/skills/agent-reach", "Claude Code"),
    ("~/.agents/skills/agent-reach", "Agent"),
]
for skill_path_template, platform_name in skill_dirs:
    skill_path = os.path.expanduser(skill_path_template)
    if os.path.isdir(skill_path):
        if dry_run: 
            print(f"[dry-run] Would remove {platform_name} skill: {skill_path}")
        else:
            if os.path.islink(skill_path):
                os.unlink(skill_path)
            else:
                shutil.rmtree(skill_path)

```

### mcporter MCP Backend Entries

The uninstaller removes **Model Context Protocol (MCP)** entries for free-search backends. Specifically, it targets the `exa` and `xiaohongshu` entries that were added during installation via `_install_mcporter`.

From lines 1436-1450:

```python
if shutil.which("mcporter"):
    for mcp_name in ("exa", "xiaohongshu"):
        r = subprocess.run(["mcporter", "list"], capture_output=True, ...)
        if mcp_name in r.stdout:
            if dry_run:
                print(f"[dry-run] Would remove mcporter entry: {mcp_name}")
            else:
                subprocess.run(["mcporter", "config", "remove", mcp_name], ...)

```

### Optional Manual Cleanup Commands

After completing the automated removal, the uninstaller prints optional commands for manual cleanup (lines 1465-1474). These are **not executed automatically**:

- `pip uninstall agent-reach` (removes the Python package)
- `npm uninstall -g mcporter` (removes the mcporter tool)
- `pipx uninstall twitter-cli` (removes Twitter CLI if installed)
- `npm uninstall -g undici` (removes undici if installed)

## How the Uninstaller Works in agent_reach/cli.py

The uninstall logic is centralized in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to keep all side-effects in one auditable location. The function signature begins at line 1375:

```python
def _cmd_uninstall(args):
    """Remove all Agent Reach config, tokens, and skill files."""
    import shutil, subprocess
    dry_run = args.dry_run
    keep_config = args.keep_config
    # [...]

```

This architecture ensures that [`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py) handles YAML reading/writing during normal operation, while [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py) orchestrates the destruction of those files during uninstall. The [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) module provides health checks that can be used to verify system state before removal, though the uninstaller proceeds regardless of channel status.

## Command-Line Options for Safe Removal

The Agent Reach uninstall process supports two critical flags for safe operation.

### Preview Changes with --dry-run

Use `--dry-run` to see exactly what would be deleted without making changes:

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

```

Example output:

```text
Agent Reach Uninstaller
========================================

[dry-run] Would remove config directory: /home/you/.agent-reach
[dry-run] Would remove OpenClaw skill: /home/you/.openclaw/skills/agent-reach
[dry-run] Would remove Claude Code skill: /home/you/.claude/skills/agent-reach
[dry-run] Would remove Agent skill: /home/you/.agents/skills/agent-reach
[dry-run] Would remove mcporter entry: exa
[dry-run] Would remove mcporter entry: xiaohongshu
Dry run complete. No changes were made.

```

### Preserve Credentials with --keep-config

Use `--keep-config` to retain your `~/.agent-reach` directory (containing tokens and API keys) while removing skill registrations and mcporter entries:

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

```

Combine both flags to preview a config-preserving removal:

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

```

## Summary

The Agent Reach uninstall process provides transparent, user-controlled cleanup of all installation artifacts:

- **Configuration data** at `~/.agent-reach` is deleted by default (unless `--keep-config` is specified)
- **Skill registrations** are removed from `~/.openclaw/skills`, `~/.claude/skills`, and `~/.agents/skills`
- **mcporter entries** for `exa` and `xiaohongshu` backends are removed via `mcporter config remove`
- **Dry-run mode** allows previewing all deletions before committing changes
- **Manual cleanup commands** are suggested but not executed for the Python package and global tools

## Frequently Asked Questions

### Does the Agent Reach uninstall process remove the Python package itself?

No. The uninstaller only removes data directories and configuration files. To completely remove the software, you must manually run `pip uninstall agent-reach` (or `pipx uninstall agent-reach`) after running the uninstall command. The CLI prints this suggestion at the end of the process.

### What happens if I interrupt the uninstall process mid-execution?

Because the uninstaller processes components sequentially (config, then skills, then mcporter), an interruption may leave some artifacts intact. Run `agent-reach uninstall --dry-run` to check the current state, then re-run the full uninstall command to complete the removal of any remaining components.

### Why does the uninstaller target specific mcporter entries rather than all entries?

The code specifically checks for and removes only the `exa` and `xiaohongshu` entries (as defined in the loop at lines 1438-1440). This prevents the uninstaller from accidentally removing unrelated MCP configurations that you may have added independently of Agent Reach.

### How does the uninstaller handle symbolic links in skill directories?

The code checks `os.path.islink()` before deletion. If a skill directory is a symlink, it uses `os.unlink()` to remove the link without affecting the target directory. Regular directories are removed using `shutil.rmtree()` (lines 1425-1430 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)).