How to Perform a Complete Uninstallation and Cleanup of Agent Reach

Run agent-reach uninstall to remove all configuration files, skill registrations, and MCP integrations, then execute pip uninstall agent-reach to delete the Python package itself.

Agent Reach is a CLI tool that integrates with multiple AI agent platforms through configuration files and skill registrations. When you need to remove it from your system, the tool provides a built-in uninstaller that ensures no residual state remains. This guide explains how to perform a complete uninstallation and cleanup of Agent Reach using the official _cmd_uninstall function implemented in agent_reach/cli.py.

What Gets Removed During Uninstallation

The uninstaller targets three specific areas of your filesystem and system configuration. According to the implementation in agent_reach/cli.py (lines 59-101), the _cmd_uninstall function removes:

1. Configuration directory (~/.agent-reach): Contains config.yaml with saved tokens, cookies, and API keys managed by the Config class in agent_reach/config.py
2. Skill registrations: Platform-specific directories including ~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, and ~/.agents/skills/agent-reach
3. MCP entries: Integration entries managed by mcporter, specifically the exa and xiaohongshu MCPs

The process is idempotent—running the uninstaller multiple times safely reports that nothing remains after the first successful execution.

Using the Built-in Uninstaller

The primary command for removing Agent Reach is implemented in agent_reach/cli.py. This function orchestrates the complete cleanup while providing safety flags to control the scope of removal.

Standard Uninstallation

To perform a complete removal of all Agent Reach files and integrations:

agent-reach uninstall

This command executes the full sequence: removing the configuration directory, deleting skill files for all supported agent platforms, and cleaning up MCP entries via mcporter.

Preview Changes with --dry-run

Before executing the removal, you can preview exactly what would be deleted using the --dry-run flag:

agent-reach uninstall --dry-run

This mode displays all paths that would be removed and issues a specific warning that the configuration directory contains credentials. No filesystem changes occur during a dry run.

Preserve Configuration with --keep-config

If you plan to reinstall Agent Reach later and want to retain your saved tokens and API keys, use the --keep-config flag:

agent-reach uninstall --keep-config

This removes skill registrations and MCP entries while preserving the ~/.agent-reach directory.

Manual Cleanup Steps

If you cannot run the built-in uninstaller, you can achieve equivalent results using standard shell commands. The following steps mirror the logic in _cmd_uninstall:

Remove the configuration directory containing secrets:

rm -rf "$HOME/.agent-reach"

Delete skill registrations for all supported agents:

rm -rf "$HOME/.openclaw/skills/agent-reach"
rm -rf "$HOME/.claude/skills/agent-reach"
rm -rf "$HOME/.agents/skills/agent-reach"

Remove MCP entries if mcporter is installed:

mcporter config remove exa
mcporter config remove xiaohongshu

Finally, remove the Python package:

pip uninstall agent-reach

Verifying Complete Removal

After uninstallation, you can verify that all channels are gone using the diagnostic utilities in agent_reach/doctor.py. The check_all and format_report functions can confirm whether any Agent Reach components remain active on your system.

Summary

• The built-in uninstaller (agent-reach uninstall) in agent_reach/cli.py provides an idempotent way to remove all state
• Three components are removed: the ~/.agent-reach config directory, skill files in ~/.openclaw, ~/.claude, and ~/.agents, and MCP entries via mcporter
• Safety flags include --dry-run for previewing changes and --keep-config for preserving credentials
• Final step requires running pip uninstall agent-reach to remove the Python package itself
• Manual cleanup is possible using standard rm -rf commands on the specific paths listed above

Frequently Asked Questions

Does the uninstaller remove the Python package?

No. The agent-reach uninstall command only removes configuration files, skill registrations, and MCP entries. You must separately run pip uninstall agent-reach to delete the Python package and CLI command from your environment.

Is it safe to run the uninstaller multiple times?

Yes. The uninstaller is idempotent. If you run agent-reach uninstall after a successful cleanup, it simply reports that the files and entries have already been removed.

What happens if I use --keep-config but delete the skill files?

The --keep-config flag specifically preserves the ~/.agent-reach directory while still removing skill files in ~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, and ~/.agents/skills/agent-reach, along with MCP entries. This allows you to reinstall later without reconfiguring API keys.

Will the uninstaller affect system-wide installations?

No. Agent Reach only touches files within the user's home directory. The uninstaller never modifies system-wide locations or requires elevated privileges, as confirmed by the implementation in agent_reach/cli.py.

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