How Agent Reach Install --safe Mode Works: Non-Destructive System Audits

The --safe flag in agent-reach install performs a read-only verification of system dependencies without making any modifications, displaying manual installation instructions for missing components instead of automatically installing them.

The install command in the Panniantong/Agent-Reach repository provides a protective --safe option designed for constrained environments. When you invoke agent-reach install with this flag, the tool switches from an automatic installer to a non-destructive auditor. This mode is particularly valuable for corporate machines, CI pipelines, or any system where you need to verify requirements before granting installation permissions.

Parsing the --safe Flag in agent_reach/cli.py

The --safe argument is defined at lines 71–73 of agent_reach/cli.py as a boolean flag. When the CLI parses user input at lines 177–178, it assigns the value to safe_mode = args.safe, which later determines the entire installation flow. This single boolean triggers a branch between two distinct execution paths: the standard automatic installation versus the safe-mode verification.

Safe Mode vs. Normal Mode: Key Differences

When --safe is present, the install command swaps its implementation functions for read-only alternatives. The behavior differs across three critical areas:

System Dependencies Handling

• Normal Mode: Calls _install_system_deps(), which attempts to automatically install missing tools like GitHub CLI and Node.js.
• Safe Mode: Calls _install_system_deps_safe() (lines 665–692), which only checks for required binaries and prints manual installation instructions.

Exa Search Backend (mcporter)

• Normal Mode: Executes _install_mcporter() to automatically install the mcporter tool via package managers.
• Safe Mode: Executes _install_mcporter_safe() (lines 962–970), which reports the presence of mcporter and displays the manual configuration command without executing it.

Optional Channel Installers

• Normal Mode: Runs channel-specific installers (e.g., Twitter, Reddit) when the --channels flag is provided.
• Safe Mode: Skips all channel-specific installers entirely, preventing any automatic package installations beyond the two core dependency checks.

How the Safe Mode Checks Work Under the Hood

The safe-mode functions implement straightforward presence checks using Python's standard library, making no subprocess calls that would modify the system.

System Dependency Validation (_install_system_deps_safe)

Located at lines 665–692 in agent_reach/cli.py, this function iterates over a small list of required tools including gh (GitHub CLI) and node (Node.js). It uses shutil.which to detect whether each binary exists on the system PATH. Missing tools are collected into a list and displayed with links to their official installation instructions. No subprocess commands are executed to install missing dependencies.

Exa Search Backend Verification (_install_mcporter_safe)

This function, found at lines 962–970, checks whether the mcporter executable is available on the PATH. If the binary is found, the function confirms its presence; otherwise, it prints a hint suggesting npm install -g mcporter for manual installation. Like its system dependency counterpart, this function performs zero automatic installations.

Using --safe with --dry-run

The --safe and --dry-run flags operate independently according to the source implementation. When you combine both flags:

agent-reach install --safe --dry-run

The --dry-run flag prints a "DRY RUN" banner before the safe-mode checks execute. However, the safe-mode behavior remains unchanged—it still suppresses any automatic system modifications and only reports what would be required. The combination provides a complete preview of both the installation plan and the dependency audit without touching the system.

Practical Example: Running a Safe Installation Check

To verify your system readiness without modifications, run:

agent-reach install --safe

The output follows this structure:

SAFE MODE — skipping automatic system changes

Checking system dependencies (safe mode — no auto-install)...
  ✅ GitHub CLI already installed
  -- Node.js not found
  To install missing dependencies manually:
    Node.js: https://nodejs.org — or: apt install nodejs npm
Checking mcporter (safe mode)...
  mcporter not found
  To install manually: npm install -g mcporter

This output allows you to review exactly which components need manual installation before proceeding with a full install.

Summary

• The --safe flag in agent-reach install switches the CLI from automatic installation to read-only verification mode.
• Two core functions handle the safe checks: _install_system_deps_safe() at lines 665–692 and _install_mcporter_safe() at lines 962–970 in agent_reach/cli.py.
• System impact is zero—safe mode uses shutil.which to detect binaries but never executes installation commands via subprocess.
• Channel installers are completely bypassed when --safe is active, even if --channels is specified.
• Combine with --dry-run to see a complete preview of the installation plan alongside the dependency audit.

Frequently Asked Questions

Does --safe modify any files on my system?

No. The --safe flag explicitly prevents any file system modifications. According to the implementation in agent_reach/cli.py, safe mode only executes detection logic using shutil.which and prints instructions. It does not invoke subprocess calls that would install packages, write configuration files, or alter your environment.

Can I use --safe and --dry-run together?

Yes. These flags are independent and complementary. When used together (agent-reach install --safe --dry-run), the CLI displays the dry-run banner followed by the safe-mode dependency audit. The dry-run flag adds preview messaging while the safe flag ensures no automatic changes occur, giving you a complete picture of what the installer would do under normal circumstances.

What dependencies does the safe mode check for?

Safe mode checks for two categories of dependencies. First, it verifies system tools including GitHub CLI (gh) and Node.js (node) through _install_system_deps_safe(). Second, it checks for the mcporter executable, which serves as the Exa search backend, through _install_mcporter_safe(). All other optional channel-specific dependencies are skipped entirely when --safe is active.

Why does safe mode skip channel installers?

Channel installers (for platforms like Twitter or Reddit) typically require additional package installations or API configurations that could modify the system. The --safe flag is designed to provide a non-destructive audit of only the core requirements needed to run Agent Reach. By skipping channel-specific installers, safe mode ensures it only reports on fundamental binary dependencies without triggering any package manager operations or network-based installations.

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