How the Agent Reach Uninstall Command Removes Skill Files and Configuration

The Agent Reach uninstall command safely removes skill files from three agent directories (OpenClaw, Claude Code, and generic Agent) while conditionally deleting the ~/.agent-reach configuration directory based on user flags.

The agent-reach uninstall sub-command in the Panniantong/Agent-Reach repository provides a controlled cleanup process for removing installed skills and configuration data. Located in agent_reach/cli.py, this command implements safety-first defaults with preview capabilities and granular control over what gets deleted.

How the Uninstall Command Parses User Flags

The uninstall handler begins by inspecting two optional arguments passed via the CLI parser. These flags determine the behavior of the entire cleanup sequence.

dry_run = args.dry_run
keep_config = args.keep_config

• --dry-run — Displays all files and directories that would be removed without making any actual changes
• --keep-config — Preserves the ~/.agent-reach directory while still removing skill files

Both flags default to False, meaning a bare agent-reach uninstall performs a full removal.

Configuration Directory Cleanup

When --keep-config is not set, the command targets the main Agent Reach configuration directory at ~/.agent-reach. The implementation in lines 1617–1634 of agent_reach/cli.py follows this logic:

1. Verify the directory exists using os.path.exists()
2. If dry_run is True, print a preview message
3. Otherwise, invoke shutil.rmtree() to recursively delete the directory and all contents

If --keep-config is specified, this entire block is skipped and the configuration persists.

Skill File Removal for Three Agent Types

The core cleanup task removes skills installed for three supported agent platforms. The uninstaller iterates over a hardcoded list of paths in lines 1652–1672:

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

For each path, the command:

• Checks if the directory exists
• Prints a dry-run message or performs deletion
• Handles symbolic links correctly to avoid traversing into unintended locations

This ensures no orphaned skill files remain in any supported agent's plugin directory.

Legacy Credential Handling

The uninstaller identifies legacy Twitter credential files used by predecessor tools xfetch and bird (lines 1636–1650). It specifically looks for:

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

These files are never automatically deleted. The command prints a warning directing users to remove them manually if desired. This conservative approach prevents accidental destruction of credentials that might be shared with other applications.

Safe MCPorter Entry Management

After skill removal, the command checks for a locally installed mcporter tool (lines 1674–1716). When found, it:

1. Enumerates configured servers in the mcporter configuration
2. Attempts to determine if entries were created by Agent Reach
3. Only deletes entries with confirmed provenance — otherwise prints a safety warning

This prevents the uninstaller from destroying MCP server configurations that might be used by other projects or manually edited by the user.

Uninstall Command Examples

Preview Mode (Dry Run)

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.

Remove Skills Only (Preserve Configuration)

agent-reach uninstall --keep-config

Complete Removal

agent-reach uninstall

After execution, the command always displays optional manual cleanup steps for removing the Python package itself via pip uninstall agent-reach.

Key Source Files and Tests

Path	Purpose
agent_reach/cli.py	Contains _cmd_uninstall implementation (lines 1598–1739)
tests/test_p0_cli.py	Unit tests for uninstall behavior with flag combinations
tests/test_skill_command.py	Tests for the _uninstall_skill helper function
agent_reach/skill/	Source skill files installed/removed by the command
agent_reach/config.py	Config class managing ~/.agent-reach/config.yaml

Summary

• The Agent Reach uninstall command targets three agent skill directories (~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, ~/.agents/skills/agent-reach) for complete removal
• Configuration cleanup is controlled by the --keep-config flag; without it, ~/.agent-reach is deleted via shutil.rmtree
• Dry-run mode (--dry-run) previews all changes without filesystem modification
• Legacy credential files and unverified MCPorter entries trigger warnings rather than 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 performs a complete removal: it deletes the ~/.agent-reach configuration directory and all three agent skill directories (OpenClaw, Claude Code, and Agent). It then prints a summary and suggests running pip uninstall agent-reach to remove the package itself.

Does the uninstall command delete my Twitter credentials?

No. The command detects legacy credential files at ~/.config/xfetch/session.json and ~/.config/bird/credentials.env but only prints a warning. You must delete these files manually if you no longer need them.

Can I preview what will be deleted before running the uninstall?

Yes. Use the --dry-run flag to see every file and directory that would be removed without making any actual changes. This is recommended before any uninstall operation.

What if I want to keep my Agent Reach configuration but remove the skills?

Add the --keep-config flag. This skips deletion of ~/.agent-reach while still removing all skill files from the three agent directories.

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