How to Uninstall Agent Reach While Preserving Configuration

Use the --keep-config flag with agent-reach uninstall to remove the tool while retaining your saved tokens, cookies, and proxy settings stored in ~/.agent-reach/config.yaml.

The open-source Agent Reach tool from the Panniantong/Agent-Reach repository provides a built-in uninstaller that completely removes skill registrations and optional tooling, but you can preserve your configuration files for future reinstalls. Understanding how to properly uninstall Agent Reach while preserving configuration ensures you don't lose API keys or authentication data when troubleshooting or upgrading.

How the Uninstaller Works in agent_reach/cli.py

The uninstall logic is implemented in the _cmd_uninstall function within agent_reach/cli.py (lines 1321-1365). When executed, the command:

1. Parses command-line arguments to detect --dry-run and --keep-config flags (args.dry_run, args.keep_config)
2. Locates the configuration directory at ~/.agent-reach (line 1329: config_dir = os.path.expanduser("~/.agent-reach"))
3. Conditionally removes the directory using shutil.rmtree (lines 1339-1350) unless --keep-config is specified
4. Cleans up skill files for supported agents like OpenClaw and Claude Code (lines 1360-1375)
5. Removes mcporter MCP entries if present, including the Exa search backend configuration (lines 1378-1395)

The critical preservation logic occurs at lines 1339-1350, where the code only executes shutil.rmtree(config_dir) when args.keep_config evaluates to false.

Preserving Configuration During Uninstallation

To retain your sensitive data while removing the tool functionality:

agent-reach uninstall --keep-config

This command preserves the entire ~/.agent-reach directory, including:

• config.yaml containing API keys and proxy settings
• Authentication cookies and tokens
• Custom user preferences

However, the uninstaller still removes:

• Skill registrations for OpenClaw, Claude Code, and generic .agents
• MCP entries for tools like the Exa search backend
• Tool-specific integrations and registrations

Previewing Changes Before Uninstalling

Before committing to removal, verify what the uninstaller will delete:

agent-reach uninstall --dry-run

This flag executes the detection logic in agent_reach/cli.py without invoking the destructive shutil.rmtree operations or deleting skill files, displaying a summary of targeted paths without making any changes to your system.

Complete Removal Workflow

For a full cleanup including the Python package itself:

# Step 1: Remove Agent Reach (using --keep-config to preserve credentials)

agent-reach uninstall --keep-config

# Step 2: Remove the Python package from your environment

pip uninstall agent-reach

# Step 3: Remove optional global helper tools if installed

npm uninstall -g mcporter
pipx uninstall twitter-cli
npm uninstall -g undici

Reinstalling After Preserved Uninstall

When you reinstall Agent Reach after using --keep-config, the installer detects the existing ~/.agent-reach directory and automatically reuses your saved credentials:

# Reinstall and auto-detect existing configuration

agent-reach install --env=auto

The installer recognizes the preserved config.yaml and loads your previous tokens, cookies, and proxy settings without requiring re-authentication.

Summary

• The uninstaller is implemented in agent_reach/cli.py within the _cmd_uninstall function (lines 1321-1365)
• Configuration files reside in ~/.agent-reach/config.yaml and contain sensitive authentication data including API keys
• Use agent-reach uninstall --keep-config to preserve settings while removing tool functionality and skill registrations
• Use --dry-run to preview deletion targets without executing changes
• Run pip uninstall agent-reach separately to remove the Python package after the tool uninstallation completes

Frequently Asked Questions

Where does Agent Reach store configuration files?

Agent Reach stores all configuration data, including API keys, cookies, and proxy settings, in the ~/.agent-reach directory, specifically within config.yaml. According to the source in agent_reach/cli.py (line 1329), this path is resolved via os.path.expanduser("~/.agent-reach").

Will uninstalling Agent Reach delete my API keys?

By default, running agent-reach uninstall without flags removes the entire ~/.agent-reach directory using shutil.rmtree, which includes your API keys and tokens. To preserve these credentials, you must include the --keep-config flag when running the uninstall command, as implemented in lines 1339-1350 of agent_reach/cli.py.

Can I see what files will be deleted before uninstalling?

Yes, you can use the --dry-run flag to preview all files and directories that would be removed. This executes the detection logic in agent_reach/cli.py without triggering the actual shutil.rmtree operations or deleting skill registrations, allowing you to verify the targets before committing to changes.

Do I need to manually remove the Python package after uninstalling?

Yes, the agent-reach uninstall command only removes configuration directories, skill files, and MCP entries according to the implementation in agent_reach/cli.py. You must separately run pip uninstall agent-reach to remove the Python package from your environment, as noted in the summary output of the uninstall command.

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