How Agent-Reach Uninstall Removes All Components: A Step-by-Step Code Breakdown

The agent-reach uninstall command removes skill directories, token files, and configuration data through a sequential cleanup process defined in agent_reach/cli.py, while preserving third-party dependencies unless explicitly requested.

The agent-reach uninstall command provides a complete cleanup mechanism for removing all tool-generated artifacts from your system. Implemented in the Agent-Reach repository (Panniantong/Agent-Reach), this CLI utility systematically deletes skill files, authentication tokens, and configuration directories while offering dry-run capabilities for safety.

The Uninstall Sequence

The uninstall logic follows a strict six-step sequence within the _cmd_uninstall function in agent_reach/cli.py. Each step targets specific components to ensure comprehensive cleanup without affecting external dependencies.

Step 1: Parsing CLI Flags

The command begins by parsing optional flags defined at lines 97–101 in agent_reach/cli.py:

• --dry-run: Displays all actions without executing file deletions
• --keep-config: Preserves the configuration directory while removing other components

Step 2: Removing Skill Files

The system calls the private helper _uninstall_skill() (defined at line 444) to remove the skills directory. By default, this targets ~/.agent-reach/skills, though the exact path is retrieved from agent_reach.utils.paths.SKILL_DIR to ensure consistency across environments. This function is invoked at line 485 within the main uninstall flow.

Step 3: Erasing Token Files

Within the same _uninstall_skill helper, the command removes authentication artifacts stored in ~/.agent-reach/tokens.json (or similar token files). The implementation uses shutil.rmtree to delete the entire token directory, ensuring no sensitive credentials remain on disk.

Step 4: Cleaning Configuration Directories

Unless the --keep-config flag is present, the command removes the configuration folder located at ~/.config/agent-reach by default. This path is defined in agent_reach.config.Config and imported through the centralized agent_reach.utils.paths module. This step occurs in _cmd_uninstall immediately after skill removal.

Step 5: Manual Cleanup Guidance

After automated removal completes, the CLI prints manual cleanup instructions (lines 1439–1444) for third-party tools that the installer may have added:

pip uninstall agent-reach
npm uninstall -g mcporter
pipx uninstall twitter-cli
npm uninstall -g undici

These components—mcporter, twitter-cli, and undici—are not deleted automatically because they may be shared with other projects, giving users explicit control over their removal.

Step 6: Dry-Run Protection

When --dry-run is specified, the command skips all filesystem mutations and outputs only the checklist from Step 5 along with a summary of what would be removed. This conditional block appears at the start of _cmd_uninstall, ensuring no destructive operations occur during preview mode.

Key Source Files and Architecture

The uninstall workflow relies on three core modules that maintain a single source of truth for system paths:

File	Role	Key Components
agent_reach/cli.py	CLI entry point	_cmd_uninstall, _uninstall_skill, argument parsing (lines 97–101), manual hints (lines 1439–1444)
agent_reach/utils/paths.py	Path constants	SKILL_DIR, CONFIG_DIR, TOKEN_FILE
agent_reach/config.py	Configuration management	Default config location for removal operations

The architecture deliberately separates automated cleanup (Agent-Reach specific files) from manual guidance (third-party packages), preventing accidental removal of system-wide tools.

Usage Examples

Run the full uninstall to remove all components including configuration:

python -m agent_reach.cli uninstall

Preview changes without deleting files:

python -m agent_reach.cli uninstall --dry-run

Preserve configuration files while removing skills and tokens:

python -m agent_reach.cli uninstall --keep-config

Example output:

Removing skill directory: /home/you/.agent-reach/skills
Removing token file: /home/you/.agent-reach/tokens.json
Removing config directory: /home/you/.config/agent-reach
You may also want to run:
  pip uninstall agent-reach
  npm uninstall -g mcporter
  pipx uninstall twitter-cli
  npm uninstall -g undici

Summary

• The agent-reach uninstall command is implemented in agent_reach/cli.py with core logic in _cmd_uninstall and _uninstall_skill.
• It removes skills from ~/.agent-reach/skills, tokens from the token directory, and configuration from ~/.config/agent-reach (unless --keep-config is used).
• All paths are centralized in agent_reach.utils.paths to ensure consistency.
• Third-party tools like mcporter and twitter-cli are not removed automatically; the command provides manual uninstall instructions instead.
• The --dry-run flag allows users to preview all deletions before execution.

Frequently Asked Questions

What files does agent-reach uninstall delete?

The command deletes three categories of files: skill directories (default ~/.agent-reach/skills), token storage files (like .agent-reach/tokens.json), and configuration directories (default ~/.config/agent-reach). Paths are resolved through agent_reach.utils.paths to ensure accuracy across different installations.

How do I preview what agent-reach uninstall will remove?

Use the --dry-run flag. When specified, the command skips all filesystem operations and prints only the checklist of what would be deleted, including the manual cleanup hints for third-party packages. This is implemented in the conditional block at the start of _cmd_uninstall in agent_reach/cli.py.

Will uninstalling Agent-Reach remove third-party tools like mcporter?

No. The automated uninstall only removes files created by Agent-Reach itself. Third-party tools such as mcporter, twitter-cli, and undici are not deleted automatically. Instead, the CLI prints manual uninstall commands (lines 1439–1444) that you can run separately if desired.

Where is the uninstall logic implemented in the source code?

The primary implementation resides in agent_reach/cli.py, specifically within the _cmd_uninstall function (which handles the command flow and configuration deletion) and the _uninstall_skill helper (which handles skill and token removal). Path constants are defined in agent_reach/utils/paths.py, and the logic is tested in tests/test_skill_command.py.

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