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

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 to ensure complete cleanup while offering flexibility for configuration preservation. The routine handles everything from API credentials stored in 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, 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 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 file remains intact with all cookies, API tokens, and proxy settings preserved.

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

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

Complete Command Reference

Execute a standard uninstallation that removes all components including credentials:

agent-reach uninstall

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

agent-reach uninstall --keep-config

Preview the uninstallation without making changes:

agent-reach uninstall --dry-run

Perform a combined safety check while preserving configuration:

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

Key Source Files

• 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: Manages the ~/.agent-reach/config.yaml file structure and persistence
• 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
• 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 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 file with all stored tokens, cookies, and API keys as defined in 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.

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, 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, 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. 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, which defines the structure of the ~/.agent-reach directory.

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