How the Agent Reach Uninstall Command Cleans Up Components

The Agent Reach uninstall command removes the configuration directory, skill installations for three agent platforms, and MCP entries, with optional --dry-run and --keep-config flags for safety.

The Agent Reach uninstall command provides a deterministic cleanup mechanism that mirrors the installation process. Located in the Panniantong/Agent-Reach repository, this CLI utility ensures complete removal of configuration files, skill registrations, and third-party MCP configurations while offering safety features to prevent accidental data loss.

Components Removed by the Uninstall Command

The uninstall routine lives in agent_reach/cli.py within the _cmd_uninstall function. It executes a sequential cleanup pipeline that targets three distinct categories of installed components.

Configuration Directory

The command first targets the ~/.agent-reach directory, which stores YAML configuration files, tokens, cookies, and API keys. According to lines 1364-1376 in agent_reach/cli.py, the code checks for directory existence using os.path.isdir before attempting removal. If the --keep-config flag is not set and the directory exists, the routine either removes it using shutil.rmtree or displays a preview message in dry-run mode.

Skill Installations for Agent Platforms

The uninstaller iterates through a hard-coded list of skill paths to remove installations across three supported agent platforms: OpenClaw, Claude Code, and generic .agents directories. As implemented in lines 1383-1401, the code deletes both directories and symlinks located at platform-specific paths such as ~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, and ~/.agents/skills/agent-reach. This logic reuses the shared _uninstall_skill helper to ensure consistency with the dedicated skill --uninstall sub-command.

MCP Registry Entries

For systems with mcporter installed, the command cleans up MCP (Model Context Protocol) entries including exa and xiaohongshu. Lines 1407-1423 verify that mcporter exists on the PATH before executing mcporter config remove <name> for each known entry. This step is silently skipped on systems where mcporter was never installed, preventing error states on minimal installations.

Safety Features and Flags

The Agent Reach uninstall command prioritizes data safety through defensive programming and user-controlled options.

Dry-Run Mode (--dry-run)

When invoked with --dry-run, the command operates in a read-only preview mode. As parsed in lines 1349-1353, setting dry_run = args.dry_run transforms every destructive action into a notification line prefixed with [dry-run]. This allows users and automation scripts to verify exactly what would be erased—configuration directories, skill paths, and MCP entries—without modifying the filesystem.

Preserving Configuration (--keep-config)

The --keep-config flag enables selective preservation of the ~/.agent-reach directory while still removing skill files and MCP entries. This is useful when users intend to reinstall Agent Reach later without reconfiguring API credentials, or when temporarily removing skill functionality while maintaining authentication state.

Implementation in agent_reach/cli.py

The core logic resides in the _cmd_uninstall function spanning lines 1349-1445. The implementation follows an idempotent pattern where each removal step checks for existence before action and catches errors without aborting the entire process. Lines 1427-1445 generate the final summary output that lists completed actions and suggests optional manual cleanup commands for the Python package (pip uninstall agent-reach) and downstream tools like mcporter or twitter-cli.

Usage Examples

Standard Uninstall

Execute a complete removal of all Agent Reach components:

agent-reach uninstall

This produces output showing each removed component:

Agent Reach Uninstaller
========================================
  Removed config directory: /home/user/.agent-reach
  Removed OpenClaw skill: /home/user/.openclaw/skills/agent-reach
  Removed Claude Code skill: /home/user/.claude/skills/agent-reach
  Removed Agent skill: /home/user/.agents/skills/agent-reach
  Removed mcporter entry: exa
  Removed mcporter entry: xiaohongshu
Agent Reach data removed.

Optional: remove the Agent Reach Python package itself:
  pip uninstall agent-reach

Preview Mode with Dry-Run

Verify what would be deleted before making changes:

agent-reach uninstall --dry-run

Output indicates preview status with [dry-run] prefixes:

Agent Reach Uninstaller
========================================
[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
[dry-run] Would remove Agent skill: /home/user/.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.
Run without --dry-run to actually remove the above.

Selective Cleanup with Keep-Config

Remove only skills and MCP entries while preserving configuration:

agent-reach uninstall --keep-config

This skips the configuration directory as shown in the output:

Agent Reach Uninstaller
========================================
  Skipping config directory (--keep-config): /home/user/.agent-reach
  Removed OpenClaw skill: /home/user/.openclaw/skills/agent-reach
  Removed Claude Code skill: /home/user/.claude/skills/agent-reach
  Removed Agent skill: /home/user/.agents/skills/agent-reach
  Removed mcporter entry: exa
  Removed mcporter entry: xiaohongshu
Agent Reach data removed.

Summary

• The Agent Reach uninstall command targets three component types: the ~/.agent-reach configuration directory, skill installations for OpenClaw/Claude Code/.agents platforms, and MCP entries via mcporter.
• All destructive operations are guarded by existence checks and error handling that prevents process abortion.
• The --dry-run flag provides a read-only preview of all actions without filesystem modification.
• The --keep-config flag preserves authentication data while removing functionality components.
• Source code resides in agent_reach/cli.py with primary logic in _cmd_uninstall (lines 1349-1445) and shared skill removal via _uninstall_skill.

Frequently Asked Questions

What happens if I run the uninstall command without flags?

Running agent-reach uninstall without flags performs a complete cleanup. It removes the ~/.agent-reach configuration directory, deletes skill installations from all three supported agent platforms (OpenClaw, Claude Code, and .agents), and removes MCP entries for exa and xiaohongshu if mcporter is installed. The command provides a summary of all actions taken and suggests commands for removing the Python package itself.

Can I recover data after running the uninstall command?

No, the uninstall command uses shutil.rmtree for directory removal, which permanently deletes files. If you need to preserve configuration data for potential reinstallation, use the --keep-config flag. For complete safety, always run --dry-run first to review what would be deleted.

Why does the uninstall command mention mcporter entries I never created?

The command maintains a hard-coded list of known MCP entries (including exa and xiaohongshu) that Agent Reach might configure during installation. The code checks if mcporter exists on your PATH before attempting removal. If you never installed mcporter or these specific entries, the command silently skips this step without error, making the uninstall process safe regardless of your specific installation history.

Is the uninstall command safe to run multiple times?

Yes, the implementation is idempotent. Each removal step checks for existence using os.path.isdir before attempting deletion, and errors are caught and reported without stopping execution. If components were already removed in a previous run, the command simply reports that nothing needed removal and completes successfully.

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