How OpenCLI Reuses Chrome Browser Sessions: Architecture and Implementation

TLDR: OpenCLI bridges your existing Chrome browser to the command line by installing a Chrome extension that reads logged-in cookies, allowing CLI tools to reuse active browser sessions without storing credentials.

OpenCLI enables command-line automation of web platforms like XiaoHongShu, Facebook, and Instagram by leveraging your existing browser authentication. Instead of managing separate credentials, it reuses your logged-in Chrome session through a local daemon and browser extension architecture. This article examines the technical implementation in the Agent-Reach repository, detailing how the system detects, maintains, and reuses browser sessions.

The Three-Component Architecture

OpenCLI operates through three integrated components that bridge the Chrome browser to command-line interfaces.

The Chrome Extension

Located in each Chrome profile under <profile>/Extensions/ildkmabpimmkaediidaifkhjpohdnifk/, the extension (identified by OPENCLI_EXTENSION_ID) serves as the browser-side bridge. According to agent_reach/backends/opencli.py lines 31-36, the system checks for this extension ID to confirm installation. The extension reads cookies from your active Chrome profiles, making logged-in sessions available to CLI tools without duplicating authentication data.

The Local Daemon

A background process manages the connection between the CLI and the Chrome extension. The opencli binary communicates with this daemon via opencli daemon status, which reports whether the service worker is active. As implemented in opencli.py lines 99-106, the daemon status indicates whether the extension is currently connected or sleeping.

The CLI Front-End

The opencli binary forwards commands like opencli xiaohongshu search or opencli facebook to the extension. When the extension's service worker is sleeping, the first command automatically wakes it. The code at opencli.py lines 12-14 handles this waking mechanism, transitioning the state from "disconnected" to "connected" after the initial call.

Session State Detection Logic

The opencli_status() function in agent_reach/backends/opencli.py distinguishes three operational states to determine session availability:

• Installed and Connected: When st.extension_connected is True (parsed from daemon output at lines 107-112), the extension is active and the Chrome login session is immediately available for reuse.
• Installed but Sleeping: When st.extension_connected is False but _extension_installed_on_disk() returns True (lines 122-125), the extension exists on disk but is inactive. The first CLI command will wake the service worker, enabling session reuse after the initial call.
• Not Installed: When _extension_installed_on_disk() returns False (lines 122-126), the extension is missing entirely. The system prompts users to install it from the Chrome Web Store before session reuse is possible.

The OpenCLISiteChannel class in agent_reach/channels/_opencli_site.py (lines 24-48) consumes these states to determine backend readiness, returning appropriate status indicators for downstream automation.

Implementation Examples

Querying OpenCLI Status from Python

from agent_reach.backends import opencli_status

st = opencli_status()
print(f"Installed: {st.installed}")
print(f"Daemon running: {st.daemon_running}")
print(f"Extension connected: {st.extension_connected}")
print(f"Ready to reuse Chrome session: {st.ready}")

This function parses daemon output, checks the Chrome profile directory for the extension ID ildkmabpimmkaediidaifkhjpohdnifk, and returns an OpenCLIStatus object indicating session availability.

Reusing Login Sessions via CLI

# After installing the OpenCLI Chrome extension and logging in to the site:

opencli xiaohongshu search "AI agents" -f yaml
opencli facebook search "Machine Learning" -f yaml
opencli instagram user "natgeo" -f yaml

The first invocation wakes a sleeping extension if necessary; subsequent commands reuse the already-connected session with existing cookies.

Checking Channel Health in Agent-Reach

from agent_reach.channels._opencli_site import OpenCLISiteChannel

channel = OpenCLISiteChannel()
channel.site = "facebook"
channel.domains = ("facebook.com",)
channel.login_hint = "facebook.com"
status, msg = channel.check()
print(status, msg)

The check() method internally calls opencli_status() and returns human-readable guidance based on the current session state, as implemented in _opencli_site.py lines 28-48.

Security Model: No Credential Duplication

OpenCLI does not store credentials locally. As documented in docs/README_en.md lines 73-75, the system "reuses your logged-in Chrome session" by reading existing cookies that Chrome already holds for authenticated users. This architecture eliminates the need for additional authentication steps while maintaining security by leveraging Chrome's existing credential storage.

Summary

• OpenCLI reuses Chrome browser sessions through a Chrome extension (ildkmabpimmkaediidaifkhjpohdnifk) installed in your browser profile directory.
• A local daemon manages the connection between the CLI and the extension, with automatic waking of sleeping service workers.
• The opencli_status() function in agent_reach/backends/opencli.py detects three states: connected, sleeping, or not installed.
• No credentials are duplicated; the system reads existing Chrome cookies to access logged-in platforms.
• Implementation in OpenCLISiteChannel provides health checks for automation workflows targeting sites like Facebook, Instagram, and XiaoHongShu.

Frequently Asked Questions

How does OpenCLI detect if the Chrome extension is installed?

The _extension_installed_on_disk() function in agent_reach/backends/opencli.py checks for the presence of the extension ID ildkmabpimmkaediidaifkhjpohdnifk within your Chrome profile's Extensions directory. It returns True if the extension files exist on disk, regardless of whether the service worker is currently active.

What happens if the OpenCLI extension is sleeping?

If the extension is installed but extension_connected is False, the first CLI command (such as opencli xiaohongshu search) automatically triggers the service worker to wake. The daemon transitions from "disconnected" to "connected" after processing the initial call, allowing subsequent commands to reuse the session immediately.

Does OpenCLI store my login credentials?

No. OpenCLI does not store passwords or authentication tokens. According to the Agent-Reach documentation, it reads cookies directly from your existing Chrome browser sessions. This design leverages Chrome's built-in credential management while exposing the authenticated state to command-line tools.

Which files handle the session reuse logic in Agent-Reach?

The primary implementation resides in agent_reach/backends/opencli.py, which probes the daemon and checks extension presence, and agent_reach/channels/_opencli_site.py, which implements OpenCLISiteChannel for site-specific session management. User-facing documentation explaining the browser session reuse appears in docs/README_en.md.

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