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

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 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 with tokens, cookies, and API keys. This directory is created by the installer and managed through agent_reach/config.py.

As implemented in agent_reach/cli.py (lines 1394-1404):

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 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):

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:

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 to keep all side-effects in one auditable location. The function signature begins at line 1375:

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 handles YAML reading/writing during normal operation, while cli.py orchestrates the destruction of those files during uninstall. The 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:

agent-reach uninstall --dry-run

Example output:

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:

agent-reach uninstall --keep-config

Combine both flags to preview a config-preserving removal:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}