How Agent Reach `uninstall` Handles Config and Skill Files: A Complete Technical Guide

The Agent Reach uninstall command removes the ~/.agent-reach configuration directory and agent-specific skill directories by default, with --keep-config and --dry-run flags for safe, previewable cleanup.

The uninstall sub-command in Agent Reach provides a deliberate, safety-first approach to removing configuration data and installed skills. Located in agent_reach/cli.py, the implementation prioritizes user control through explicit flags and careful handling of potentially sensitive files.

The Uninstall Command Entry Point

The _cmd_uninstall function in agent_reach/cli.py (lines 1598-1739) implements the full uninstallation logic. It interprets two primary flags that control behavior:

dry_run = args.dry_run
keep_config = args.keep_config

• --dry-run: Preview all deletions without modifying the filesystem
• --keep-config: Preserve the ~/.agent-reach configuration directory while removing skills

Handling the Configuration Directory

Default Behavior: Full Config Removal

Unless --keep-config is specified, the uninstaller targets ~/.agent-reach—the central configuration directory containing config.yaml and other runtime data. The logic at lines 1617-1634 checks for directory existence, then either prints the path (dry-run mode) or executes shutil.rmtree for actual deletion.

# Remove config + skills (default behavior)

$ agent-reach uninstall

Output:

Agent Reach Uninstaller
========================================
Removed config directory: /home/user/.agent-reach
...

Preserving Configuration with --keep-config

When --keep-config is passed, the configuration directory remains untouched. Only skill installations are removed, allowing users to retain their Agent Reach settings for potential reinstallation.

# Remove skills only, keep config

$ agent-reach uninstall --keep-config

Output:

Agent Reach Uninstaller
========================================
[skip] Keeping config directory: /home/user/.agent-reach
Removed OpenClaw skill: /home/user/.openclaw/skills/agent-reach
...

Removing Installed Skill Files

Agent Reach installs skills for three compatible agent environments. The uninstaller iterates through each location at lines 1652-1672:

Agent	Skill Directory Path
OpenClaw	~/.openclaw/skills/agent-reach
Claude Code	~/.claude/skills/agent-reach
Generic Agent	~/.agents/skills/agent-reach

For each existing directory, the command:

• Prints the action (dry-run) or removes the directory
• Handles symlinks correctly
• Skips non-existent installations silently

The underlying helper _uninstall_skill (tested in tests/test_skill_command.py) manages the actual filesystem operations.

Safety Mechanisms for Related Files

Legacy Credential Warnings (Lines 1636-1650)

The uninstaller detects legacy Twitter credential files from related tools xfetch and bird:

• ~/.config/xfetch/session.json
• ~/.config/bird/credentials.env

These files are never deleted automatically. Instead, a warning prompts manual cleanup:

⚠️  Found legacy credential files that are NOT removed automatically:
   - ~/.config/xfetch/session.json
   - ~/.config/bird/credentials.env

mcporter Server Entries (Lines 1674-1716)

If mcporter is locally installed, the uninstaller enumerates its configured servers. Without positive proof that an entry was created by Agent Reach, no deletions occur—a conservative approach preventing accidental disruption of unrelated server configurations.

Preview Mode: --dry-run Workflow

The dry-run flag enables complete visibility before any changes:

$ agent-reach uninstall --dry-run

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 complete. No changes were made.

This satisfies the principle of safe-by-default execution: users verify scope before committing to deletion.

Finalization and Manual Cleanup Notes

The uninstaller concludes with contextual output (lines 1718-1739):

• Confirmation of actual deletions performed
• No-op notification for dry-runs
• Optional guidance for removing the Python package itself:

Agent Reach data removed.
Optional: remove the Agent Reach Python package itself:
  pip uninstall agent-reach
Optional: remove globally installed tools (if any):
  rm /usr/local/bin/agent-reach  # or similar

Key Source Files and Test Coverage

Path	Responsibility
agent_reach/cli.py	_cmd_uninstall implementation (lines 1598-1739)
tests/test_p0_cli.py	Unit tests for dry_run and keep_config flag behavior
tests/test_skill_command.py	Tests for the _uninstall_skill helper
agent_reach/config.py	Config class managing ~/.agent-reach/config.yaml
agent_reach/skill/	Skill source files referenced during uninstall verification

Summary

• The uninstall command uses --dry-run for preview and --keep-config to preserve settings
• Configuration lives in ~/.agent-reach; skills install to agent-specific subdirectories
• Three skill targets are checked: OpenClaw, Claude Code, and generic Agent
• Safety guards protect legacy credentials and unverified mcporter entries from automatic deletion
• All logic resides in agent_reach/cli.py with comprehensive test coverage in tests/test_p0_cli.py

Frequently Asked Questions

What happens if I run uninstall without any flags?

The command removes the ~/.agent-reach configuration directory and all three agent skill directories (OpenClaw, Claude Code, Agent). It executes shutil.rmtree on each existing path after verifying presence.

Can I uninstall skills without losing my Agent Reach settings?

Yes. Pass the --keep-config flag: agent-reach uninstall --keep-config. This skips deletion of ~/.agent-reach while removing all installed skill directories.

Does the uninstaller delete my Twitter or API credentials?

No. Legacy credential files at ~/.config/xfetch/session.json and ~/.config/bird/credentials.env are detected but never removed automatically. A warning notifies you of their presence for optional manual deletion.

How do I verify what will be deleted before running uninstall?

Use agent-reach uninstall --dry-run. This prints every filesystem operation that would occur without making actual changes, including config directory removal and each skill directory deletion.

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