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

> Learn how the Agent Reach uninstall command handles config and skill files. Discover the default behavior and useful flags like --keep-config for a complete technical guide.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1598-1739) implements the full uninstallation logic. It interprets two primary flags that control behavior:

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

```bash

# 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.

```bash

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

```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.

```

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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | `_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 `dry_run` and `keep_config` flag behavior |
| [`tests/test_skill_command.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_skill_command.py) | Tests for the `_uninstall_skill` helper |
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](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 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.