How Agent-Reach Auto-Detects Local vs Server Environments for OpenCLI

Agent-Reach automatically detects whether the OpenCLI backend is usable by probing the OpenCLI binary, its daemon status, and the presence of the Chrome extension folder on disk—falling back to server-side alternatives when the extension is absent.

Agent-Reach is an open-source automation framework that routes commands to different backends depending on the runtime environment. To determine whether OpenCLI (a browser-automation backend requiring Chrome) can run on the current machine, Agent-Reach implements a multi-layered detection system in agent_reach/backends/opencli.py.

Why Environment Detection Matters for OpenCLI

OpenCLI relies on a Chrome browser session for authentication and operation. While this works perfectly on local desktops with graphical environments, it fails on headless servers lacking Chrome. Agent-Reach solves this by probing the system before attempting to use OpenCLI, ensuring seamless fallback to API-based or CLI-only backends on server environments.

The Four-Layer Detection Mechanism in opencli.py

The detection logic runs through four distinct checks before marking OpenCLI as ready.

1. Binary Presence Check

The detection starts by verifying the OpenCLI command exists. In agent_reach/backends/opencli.py lines 80-87, the opencli_status function runs opencli --version. If the command returns a non-zero exit code or is missing, installed is set to False and the backend is immediately marked unavailable.

2. Daemon and Extension Connection Status

Next, the probe executes opencli daemon status and parses the output to set two boolean flags: daemon_running and extension_connected (lines 99-112). This reveals whether the OpenCLI daemon is active and whether the Chrome extension is currently communicating with it.

3. Extension Folder Detection on Disk

Because a disconnected extension may still be present (it wakes on the first real call), the code checks for the extension folder in typical Chrome profile locations. On macOS/Linux, it searches _CHROME_PROFILE_ROOTS; on Windows, it checks %LOCALAPPDATA% (lines 40-55). If the folder exists, extension_installed becomes True.

4. The ready Property Decision Logic

The final determination happens in the OpenCLIStatus.ready property (lines 68-77). This returns True only when OpenCLI is installed, not broken, and either the extension is already connected or the extension files are present on disk. On servers without Chrome, the extension folder is absent, so ready returns False.

How Channel Routing Uses the Detection Results

Each channel defines an ordered list of preferred backends. For example, xiaohongshu.py specifies ["OpenCLI", "xiaohongshu-mcp", "xhs-cli"] (lines 152-155). The core routing logic in agent_reach/core.py iterates through this list, calling opencli_status() for each backend. It selects the first backend where ready is True. Consequently, desktop machines with Chrome use OpenCLI, while servers automatically fall back to MCP or CLI alternatives.

Practical Implementation Examples

Here is how to probe the current environment programmatically:

from agent_reach.backends.opencli import opencli_status

# Probe the current machine

status = opencli_status()

if status.ready:
    print("OpenCLI is usable – we are on a desktop with Chrome.")
else:
    print("OpenCLI not ready – falling back to server-side backends.")

The opencli_summary function (lines 24-36) generates user-visible status strings like "未安装" (not installed), "已安装但扩展未安装" (installed but extension not installed), or "可用（浏览器登录态）" (available with browser login), which the CLI displays when showing the active backend.

Summary

Agent-Reach's environment detection ensures OpenCLI only runs where it can succeed:

• Binary check: Verifies opencli is installed via opencli --version
• Daemon check: Confirms opencli daemon status reports a running daemon
• Extension probe: Looks for Chrome extension files in standard profile directories
• Ready flag: Combines these checks to determine desktop vs server eligibility
• Automatic fallback: Core routing selects the first ready backend from the channel's priority list

Frequently Asked Questions

How does Agent-Reach detect if OpenCLI is installed?

Agent-Reach runs opencli --version in a subprocess. If the command exits with an error or is not found in the system PATH, the installed flag is set to False in agent_reach/backends/opencli.py (lines 80-87).

What happens if Chrome is installed but the extension is not running?

The probe checks for the extension folder on disk in standard Chrome profile locations. If the files exist, extension_installed is True, and the ready property returns True because the extension will wake on the first actual call.

How does the routing system choose between OpenCLI and server backends?

Each channel defines a prioritized list of backends (e.g., ["OpenCLI", "xiaohongshu-mcp"]). The core routing logic in agent_reach/core.py iterates through this list and selects the first backend where opencli_status().ready is True.

Can I force OpenCLI to run on a server without Chrome?

No. If the Chrome extension folder is absent from standard profile locations and the extension is not connected, ready will be False, causing the router to skip OpenCLI and use the next available backend.

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