How OpenCLI Integrates as a Cross-Platform Browser Backend in Agent-Reach

OpenCLI serves as a desktop-only browser backend in Agent-Reach by probing the user's existing Chrome login sessions through the @jackwener/opencli npm package, providing health checks, channel glue, and CLI orchestration across macOS, Linux, and Windows.

Agent-Reach leverages OpenCLI to bridge web automation without requiring per-platform credentials or headless browser management. This integration allows the framework to reuse existing Chrome sessions through a lightweight Node.js wrapper, making it a true cross-platform browser backend for sites like Facebook, Instagram, and Twitter.

Architecture Overview

The integration spans three tightly coupled layers: backend health checks in agent_reach/backends/opencli.py, channel-level abstractions in agent_reach/channels/_opencli_site.py, and CLI orchestration in agent_reach/cli.py. Together, these components enable Agent-Reach to treat OpenCLI as a first-class browser automation backend that reuses the user's existing Chrome/Chromium login sessions.

Backend Health Checks and Discovery

The OpenCLIStatus Dataclass

In agent_reach/backends/opencli.py, the opencli_status() function probes the OpenCLI binary without side effects. It checks the binary version (--version), daemon status (daemon status), and whether the Chrome extension is installed on disk. Results populate an OpenCLIStatus dataclass exposing boolean properties such as installed, broken, daemon_running, extension_connected, extension_installed, and a convenience ready flag that returns True when the extension is either connected or installed but sleeping.

User-Facing Diagnostics

The opencli_summary() function transforms the OpenCLIStatus object into a short, user-facing one-line description. When the extension is installed but dormant, or fully connected, the summary provides actionable hints for CLI output, ensuring users understand whether their browser login state is accessible.

Channel-Level Integration with OpenCLISiteChannel

The Base Class Abstraction

Platforms accessible purely through OpenCLI inherit from OpenCLISiteChannel defined in agent_reach/channels/_opencli_site.py. This base class implements the check() method which calls opencli_status() and maps results to four framework states:

• off — OpenCLI is not installed → instructs the user to run agent-reach install --channels opencli
• error — Binary exists but is broken → displays the hint from the status object
• ok — Usable now with browser login present → shows the usage string
• warn — Installed but extension is asleep or missing → provides the appropriate wake hint

Concrete Channel Implementations

Concrete channels like FacebookChannel and InstagramChannel declare only site, domains, usage, and login_hint attributes in agent_reach/channels/facebook.py and agent_reach/channels/instagram.py. All runtime logic remains in the shared base class, ensuring consistent OpenCLI integration without duplicating health-check code across channels.

CLI Installation and Orchestration

The agent_reach/cli.py module handles OpenCLI setup through the internal _install_opencli_deps helper. When users run agent-reach install --channels opencli, the CLI prints diagnostics via opencli_summary() and, if needed, suggests the installation command npm install -g @jackwener/opencli.

Channels exclusive to OpenCLI—including Facebook, Instagram, and the generic "opencli" channel—populate the OPENCLI_ONLY_CHANNELS set. This ensures they install only on desktop environments and are automatically skipped in server-only runs, maintaining the cross-platform browser backend's desktop-only scope.

Cross-Channel Fallback Logic

Some channels treat OpenCLI as a secondary backend rather than the primary interface. In agent_reach/channels/twitter.py, the check() method builds an ordered_backends list, evaluating native tools like twitter-cli or bird first. If OpenCLI reports ready and preferred tools are absent, it becomes the active backend, surfacing usage strings such as opencli twitter search/article/user-posts -f yaml to the agent.

Practical Code Examples

Install OpenCLI through the Agent-Reach CLI (desktop only):

python -m agent_reach.cli install --channels opencli

# Output: OpenCLI 可用（浏览器登录态，v1.8.3）

Read content from an OpenCLI-backed channel like Facebook:

agent-reach read "https://www.facebook.com/OpenAI"

# Internally:

#   → FacebookChannel.check() calls opencli_status()

#   → If ready, returns ("ok", "opencli facebook search/profile/feed...")

#   → Agent executes: opencli facebook search/profile/feed -f yaml <url>

Programmatically check OpenCLI status in Python:

from agent_reach.backends import opencli_status, opencli_summary

st = opencli_status()
print(opencli_summary(st))  # One-line health description

Demonstrate Twitter's fallback to OpenCLI:

from agent_reach.channels.twitter import TwitterChannel

ch = TwitterChannel()
status, msg = ch.check()
print(status, msg)  # May be "ok" via OpenCLI if twitter-cli is missing

Summary

• OpenCLI acts as a desktop-only, cross-platform browser backend that reuses existing Chrome login sessions through the @jackwener/opencli npm package.
• The OpenCLIStatus dataclass in agent_reach/backends/opencli.py provides granular health checks covering binary presence, daemon status, and extension connectivity.
• OpenCLISiteChannel in agent_reach/channels/_opencli_site.py offers a reusable base class for OpenCLI-only sites, with concrete implementations like Facebook and Instagram defining only metadata.
• The CLI orchestration in agent_reach/cli.py manages installation through _install_opencli_deps and maintains the OPENCLI_ONLY_CHANNELS set for desktop-only deployments.
• Fallback logic in channels like Twitter allows OpenCLI to serve as a backup when native CLI tools are unavailable, ensuring maximum compatibility across platforms.

Frequently Asked Questions

What is OpenCLI in Agent-Reach?

OpenCLI is the @jackwener/opencli npm package that Agent-Reach treats as a browser automation backend. It connects to the user's existing Chrome/Chromium installation to reuse login sessions, eliminating the need for separate credential management or headless browser setup.

How does Agent-Reach check if OpenCLI is ready?

The framework calls opencli_status() from agent_reach/backends/opencli.py, which probes the binary version, daemon status, and Chrome extension state. The resulting OpenCLIStatus object exposes a ready property that indicates whether the extension is connected or installed but sleeping, allowing channels to determine if they can execute browser commands.

Can OpenCLI be used on headless servers?

No. OpenCLI is explicitly designed as a desktop-only backend. The OPENCLI_ONLY_CHANNELS set in agent_reach/cli.py ensures these channels are skipped in server-only environments, as they require a local Chrome installation with user login sessions.

Which channels support OpenCLI as a fallback?

While Facebook, Instagram, and Bilibili use OpenCLI as their primary backend, channels like Twitter in agent_reach/channels/twitter.py implement fallback logic. They first check for native tools like twitter-cli, then fall back to OpenCLI if it reports ready and native tools are unavailable.

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