How OpenCLI Integration Works for Platform Access in Agent-Reach

Agent-Reach implements OpenCLI integration by probing the local CLI installation and Chrome extension status through the opencli_status() helper, then routing platform requests via the OpenCLISiteChannel class to leverage existing browser login sessions without requiring API credentials.

Agent-Reach treats OpenCLI as a first-class backend for accessing platforms like Instagram and Facebook through the user's authenticated Chrome session. This OpenCLI integration eliminates the need for separate API keys or OAuth flows by reusing existing login cookies from the browser. The architecture follows a three-step validation flow: probing the installation, exposing a reusable channel abstraction, and implementing concrete platform-specific channels.

Step 1: Probing the OpenCLI Installation

The integration begins in agent_reach/backends/opencli.py with the opencli_status() helper function. This utility runs a series of non-side-effect commands to verify the environment:

• opencli --version confirms the CLI exists and is executable.
• opencli daemon status checks that the daemon is running and whether the Chrome extension is connected.

If the extension appears disconnected, the helper scans local Chrome profiles for the OpenCLI extension folder (<profile>/Extensions/<extension-id>/). This distinguishes between a sleeping extension and a completely absent installation, allowing Agent-Reach to provide specific remediation guidance.

Step 2: The OpenCLISiteChannel Abstraction

Platform access is abstracted through OpenCLISiteChannel in agent_reach/channels/_opencli_site.py. This class inherits from the generic Channel base and implements two critical methods:

• can_handle(url): Matches the request host against a domains tuple declared by concrete subclasses (e.g., instagram.com, facebook.com).
• check(config=None): Validates backend health by calling opencli_status() and returns standardized status tuples:
  • ("off", hint) if OpenCLI is missing, including the installation command agent-reach install --channels opencli.
  • ("error", hint) if the CLI is broken.
  • ("ok", usage-message) if the daemon and extension are ready, setting self.active_backend = "OpenCLI".
  • ("warn", hint) if the extension is missing, providing the Chrome Web Store URL (https://chromewebstore.google.com/detail/opencli/<extension-id>).

Step 3: Concrete Platform Implementations

Each supported platform subclasses OpenCLISiteChannel and supplies static metadata. This design allows Agent-Reach to add new platforms without modifying core routing logic.

In agent_reach/channels/instagram.py, the InstagramChannel class defines:

• site = "instagram"
• domains = ("instagram.com", "instagr.am")
• Usage strings for CLI commands and login hints pointing to instagram.com

Similarly, agent_reach/channels/facebook.py defines analogous values for Facebook URLs. These concrete implementations require only metadata configuration; all execution logic remains inherited from the base OpenCLISiteChannel.

Request Routing and Backend Selection

When an agent calls agent_reach.core.read(url) or search(query), the channel registry in agent_reach/channels/__init__.py selects the first channel whose can_handle method matches the URL. If the chosen channel is an OpenCLISiteChannel subclass, Agent-Reach invokes the OpenCLI backend directly via subprocess calls (e.g., opencli instagram search/profile/user -f yaml). The framework never re-implements platform logic; it merely routes requests and reports health status.

Benefits of the OpenCLI Architecture

Zero-configuration access: The user's existing Chrome login cookies are reused automatically, eliminating separate API key management or OAuth flows.

Desktop-only, non-headless execution: The Chrome extension runs in the user's real browser instance, preserving session state including two-factor authentication cookies and JavaScript-rendered content.

Graceful degradation: If the OpenCLI daemon is not running or the extension is missing, the check method returns specific warning states with actionable remediation steps, including one-click installation URLs.

Implementation Example

The following example demonstrates resolving a URL to its channel, verifying backend health, and constructing the appropriate CLI command:

from agent_reach.channels import get_channel

# Resolve URL to the appropriate channel

url = "https://www.instagram.com/openai/"
channel = get_channel("instagram")  # InstagramChannel subclass of OpenCLISiteChannel

# Verify backend health (normally done by the CLI "doctor" command)

status, msg = channel.check()
print(status)  # → "ok", "warn", "off", or "error"

print(msg)     # Human-readable guidance

# Construct the OpenCLI command that agents execute directly

command = f"opencli {channel.site} search/profile/user -f yaml 'openai'"
print("Run:", command)

On a machine with a working OpenCLI installation, this outputs:

ok
OpenCLI 可用（复用浏览器登录态）。用法：opencli instagram search/profile/user -f yaml。若提示登录，请先在 Chrome 里登录 instagram.com
Run: opencli instagram search/profile/user -f yaml 'openai'

If OpenCLI is not installed, the check call returns "off" with installation instructions:

off
未安装 Instagram 后端。安装：
  agent-reach install --channels opencli
然后在 Chrome 里登录 instagram.com

Key Source Files and Components

• agent_reach/backends/opencli.py: Contains opencli_status() for detecting installation, daemon status, and Chrome extension presence.
• agent_reach/channels/_opencli_site.py: Implements the OpenCLISiteChannel base class with can_handle() and check() methods.
• agent_reach/channels/instagram.py: Concrete subclass providing Instagram-specific domain matching and metadata.
• agent_reach/channels/facebook.py: Concrete subclass for Facebook platform access.
• agent_reach/channels/__init__.py: Channel registry that discovers and instantiates all available channels including OpenCLI variants.

Summary

• Agent-Reach probes OpenCLI installation health via opencli_status() in agent_reach/backends/opencli.py, checking CLI availability, daemon status, and Chrome extension connectivity.
• The OpenCLISiteChannel class in agent_reach/channels/_opencli_site.py provides a reusable abstraction for validating and routing requests to OpenCLI-supported platforms.
• Concrete implementations like InstagramChannel and FacebookChannel require only domain tuples and site identifiers, inheriting all execution logic from the base class.
• The channel registry in agent_reach/channels/__init__.py automatically selects and invokes the appropriate OpenCLI backend based on URL matching.
• OpenCLI integration enables zero-configuration platform access by reusing existing Chrome sessions, with graceful degradation when components are missing.

Frequently Asked Questions

What is OpenCLI in the context of Agent-Reach?

OpenCLI is a command-line tool paired with a Chrome extension that allows Agent-Reach to interact with websites using the user's existing browser session. Agent-Reach treats OpenCLI as a backend driver, routing requests through the CLI rather than implementing custom HTTP clients or API integrations for each platform.

How does Agent-Reach verify that OpenCLI is ready for platform access?

Agent-Reach calls opencli_status() from agent_reach/backends/opencli.py, which executes opencli --version and opencli daemon status to confirm the CLI exists and the daemon is running. It also scans Chrome profile directories for the extension folder to verify the browser component is installed, returning detailed status codes that inform the user of specific missing components.

Can OpenCLI integration work without the Chrome extension?

No. The OpenCLI integration requires both the CLI daemon and the Chrome extension to function. If the extension is disconnected or missing, the check() method in OpenCLISiteChannel returns a ("warn", hint) status with a link to the Chrome Web Store installation page. The extension is essential for accessing the user's authenticated session cookies in the browser.

Which platforms are currently supported through OpenCLI integration?

According to the source code, Instagram and Facebook are implemented as concrete subclasses. The InstagramChannel in agent_reach/channels/instagram.py handles instagram.com and instagr.am domains, while the Facebook channel in agent_reach/channels/facebook.py handles Facebook URLs. Additional platforms can be supported by creating new subclasses of OpenCLISiteChannel with appropriate domain tuples.

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