How the `agent-reach install --safe` Flag Works for Non-Destructive Audits

The --safe flag triggers a non-destructive audit mode that checks for required system dependencies and the mcporter backend without installing anything, printing manual installation instructions instead of modifying your system.

The agent-reach install command in the Panniantong/Agent-Reach repository provides a --safe option for users who need to verify requirements without granting the installer system modification privileges. When activated, this mode bypasses all automatic package installations and instead performs read-only checks using shutil.which to report missing binaries. This approach is ideal for corporate environments, CI pipelines, or any system where you prefer to manage dependencies manually.

CLI Flag Definition and Parsing

In agent_reach/cli.py, the --safe argument is defined at lines 71-73. When the _cmd_install function executes, it captures this value at lines 177-178 into a safe_mode variable that controls the branching logic for the remainder of the installation process.

Rather than invoking the standard installation helpers, the CLI substitutes alternative "safe" functions that perform verification only.

Safe Mode vs. Normal Installation Logic

The installer replaces three key operations with safe equivalents when --safe is passed:

System Dependency Handling

Normal mode calls _install_system_deps(), which attempts to automatically install missing tools like GitHub CLI (gh) and Node.js using subprocess commands.

In --safe mode, the code invokes _install_system_deps_safe() (lines 665-692). This function iterates through the required binaries and uses shutil.which to verify their presence on the system PATH. Missing tools are collected and displayed with manual installation instructions, but no subprocess calls are executed to install anything.

Exa Search Backend (mcporter)

When installing the Exa search backend, normal execution runs _install_mcporter() to automatically set up the mcporter tool via npm.

The safe mode alternative, _install_mcporter_safe() (lines 962-970), simply checks whether the mcporter executable exists. If found, it confirms the installation; otherwise, it prints the manual installation command (npm install -g mcporter) without modifying the system.

Optional Channel Installers

The installer typically runs channel-specific installers (for Twitter, Reddit, etc.) when the --channels flag is provided. Under --safe mode, these installers are skipped entirely to prevent any automatic package modifications beyond the core dependency checks.

Combining with --dry-run

You can combine --safe with --dry-run for additional visibility. When both flags are present, the CLI prints a "DRY RUN" banner before executing the safe-mode checks, though the safe-mode behavior remains unchanged—no system modifications occur in either case.

Usage Example

# Audit system requirements without installing anything

agent-reach install --safe

Expected output:

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

To preview with dry-run messaging:

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

Summary

• The agent-reach install --safe command switches from automatic installation to read-only verification
• System dependencies are checked via shutil.which in _install_system_deps_safe() (lines 665-692) rather than installed
• The mcporter backend is verified but not installed via _install_mcporter_safe() (lines 962-970)
• All optional channel installers are bypassed when --safe is active
• The mode can be combined with --dry-run for preview purposes without system changes

Frequently Asked Questions

Does --safe install any packages automatically?

No. According to the source code in agent_reach/cli.py, safe mode uses shutil.which to verify binary presence and prints manual instructions. No subprocess calls are made to install packages, and optional channel installers are completely skipped.

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

Yes. These flags operate independently according to the implementation at lines 177-178. When combined, the CLI prints dry-run messaging before executing the safe-mode checks, but neither flag allows the installer to modify your system.

What specific tools does safe mode check for?

The _install_system_deps_safe() function specifically checks for the GitHub CLI (gh) and Node.js (node) binaries. The _install_mcporter_safe() function checks for the mcporter executable required for Exa search functionality, as implemented at lines 962-970.

Where is the safe mode logic implemented?

All safe mode functionality resides in agent_reach/cli.py. The flag is parsed at lines 71-73, assigned at lines 177-178, and implemented in the _install_system_deps_safe() and _install_mcporter_safe() functions at lines 665-692 and 962-970 respectively.

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