# How the Agent Reach Uninstall Command Removes Skill Files and Configuration

> Discover how the Agent Reach uninstall command efficiently removes skill files and cleans up configuration, ensuring a complete removal.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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)

```bash
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)

```bash
agent-reach uninstall --keep-config

```

### Complete Removal

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Contains `_cmd_uninstall` implementation (lines 1598–1739) |
| [`tests/test_p0_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_p0_cli.py) | Unit tests for uninstall behavior with flag combinations |
| [`tests/test_skill_command.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) with comprehensive test coverage in [`tests/test_p0_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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.