How to Uninstall Agent Reach While Preserving Configuration

You can uninstall Agent Reach while keeping your saved tokens, cookies, and API settings by using the --keep-config flag, which prevents the removal of the ~/.agent-reach directory containing your credentials.

Agent Reach from the Panniantong/Agent-Reach repository includes a built-in uninstaller that removes skill registrations, MCP entries, and tooling, but you can uninstall Agent Reach while preserving configuration by passing a specific command-line flag. This ensures your config.yaml—which stores sensitive authentication data—remains intact for future reinstallation.

Understanding the Agent Reach Uninstaller

The uninstaller logic resides in agent_reach/cli.py within the _cmd_uninstall function (lines 1321–1365). When you execute agent-reach uninstall, the CLI parses arguments for --dry-run and --keep-config flags before targeting the configuration directory at ~/.agent-reach.

Without preservation flags, the uninstaller uses shutil.rmtree (lines 1339–1350) to delete the entire ~/.agent-reach directory, which houses your config.yaml along with cookies and proxy settings. It then proceeds to remove skill files for supported agents like OpenClaw and Claude Code (lines 1360–1375) and cleans up any mcporter MCP entries (lines 1378–1395).

Using the --keep-config Flag

To preserve your authentication data while removing the application components, append the --keep-config flag to your uninstall command. This skips the deletion of the ~/.agent-reach directory while still removing skill registrations and optional tooling.

Run the following command to uninstall Agent Reach while preserving configuration:

agent-reach uninstall --keep-config

This command executes the full uninstallation sequence defined in agent_reach/cli.py but bypasses the shutil.rmtree call on your configuration folder. Your tokens, API keys, and saved cookies remain stored in ~/.agent-reach/config.yaml for immediate reuse upon reinstallation.

Testing with --dry-run

Before committing to changes, use the --dry-run flag to preview what the uninstaller will remove. This mode prints a summary without executing any deletions.

# Preview what will be removed without making changes

agent-reach uninstall --dry-run

When combined with --keep-config, you can verify exactly which files will remain:

# Preview uninstallation while showing config preservation

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

Complete Uninstallation Workflow

For a full cleanup including the Python package itself, follow this sequence after running the Agent Reach uninstaller:

# Step 1: Remove Agent Reach application data (keep config)

agent-reach uninstall --keep-config

# Step 2: Remove the Python package

pip uninstall agent-reach

# Step 3: Optional - remove globally-installed helper tools

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

To restore Agent Reach later while reusing your preserved credentials:

# Reinstall will detect existing ~/.agent-reach and reuse saved tokens

agent-reach install --env=auto

What Gets Removed vs. Preserved

Understanding the distinction between application data and configuration helps prevent accidental credential loss:

Removed by default (all modes):

• Skill files for integrated agents (OpenClaw, Claude Code, generic .agents)
• mcporter MCP entries including the Exa search backend configuration
• Application binaries and CLI tooling

Removed only without --keep-config:

• The entire ~/.agent-reach directory containing config.yaml
• All stored cookies, API keys, and proxy settings

Preserved when using --keep-config:

• ~/.agent-reach/config.yaml and all credential stores
• User preferences and environment settings
• Channel configurations managed by agent_reach/config.py

Verifying the Uninstall

After uninstallation, verify that components were properly removed using the diagnostic tools in agent_reach/doctor.py. The check_all function can confirm that skill registrations and MCP entries were cleared while your configuration remains accessible.

Check that your configuration directory still exists:

ls ~/.agent-reach

# Should show config.yaml if --keep-config was used

# Should return "No such file or directory" if fully removed

Summary

• The uninstaller in agent_reach/cli.py (lines 1321–1365) handles complete removal of Agent Reach components.
• Use --keep-config to prevent deletion of the ~/.agent-reach directory containing your config.yaml credentials.
• The --dry-run flag lets you preview changes without executing them.
• Skill files and mcporter entries are always removed during uninstallation regardless of configuration preservation.
• After uninstalling the application data, run pip uninstall agent-reach to remove the Python package itself.
• Your preserved configuration in ~/.agent-reach will be automatically detected during future installations.

Frequently Asked Questions

How do I completely remove Agent Reach including all my saved credentials?

Run agent-reach uninstall without the --keep-config flag. This executes shutil.rmtree on the ~/.agent-reach directory (lines 1339–1350 in agent_reach/cli.py), permanently deleting your config.yaml along with all stored tokens, cookies, and API keys. Follow up with pip uninstall agent-reach to remove the Python package.

Will preserving configuration allow me to reinstall without re-authenticating?

Yes. When you use agent-reach uninstall --keep-config, the ~/.agent-reach directory persists with your config.yaml intact. The Agent Reach installer detects this existing directory during reinstallation and reuses your saved authentication tokens and cookies, allowing immediate access without re-entering credentials.

What happens to the mcporter MCP entries when I uninstall?

The uninstaller removes mcporter MCP entries (such as the Exa search backend configuration) regardless of whether you use --keep-config. These entries are managed separately from your personal credentials and are cleaned up via the code path at lines 1378–1395 in agent_reach/cli.py to ensure no residual service connections remain.

Can I uninstall Agent Reach if I installed it with pipx instead of pip?

Yes. The agent-reach uninstall command works the same way regardless of your installation method. However, after completing the uninstall command, use pipx uninstall agent-reach instead of pip uninstall agent-reach to remove the isolated environment. Your configuration preservation strategy remains identical.

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