How OpenCLI Reuses Chrome Browser Sessions for Authenticated Access

OpenCLI reuses authenticated Chrome sessions by installing a browser extension that reads existing cookies from your logged-in profiles, eliminating the need for separate credential storage or manual authentication steps.

The Panniantong/Agent-Reach repository implements OpenCLI as a bridge between Chrome's authenticated state and command-line tools. This architecture allows Agent Reach to interact with platforms like XiaoHongShu, Facebook, and Instagram without handling passwords or tokens directly. Understanding how OpenCLI reuses Chrome browser sessions for authenticated access is essential for developers building automated agents that require authenticated API access.

The Three-Component Architecture

OpenCLI operates through a coordinated system involving a Chrome extension, local daemon, and CLI front-end. This design ensures that your existing browser authentication is immediately available to command-line scripts.

The Browser Extension

The OpenCLI extension is identified by the ID ildkmabpimmkaediidaifkhjpohdnifk. When installed, it resides within each Chrome profile directory at <profile>/Extensions/<extension-id>/ according to the path resolution in agent_reach/backends/opencli.py【opencli.py†L31-L36】. This extension reads cookies from the active Chrome session without exporting them to external storage.

The Local Daemon

A background process maintains communication between the CLI and the browser extension. The opencli daemon status command queries this process to determine whether the extension is currently connected (service worker awake) or disconnected【opencli.py†L99-L106】. The daemon reports real-time connection states that determine whether authenticated requests can proceed immediately.

The CLI Front-End

The opencli binary forwards platform-specific commands (such as opencli xiaohongshu search or opencli facebook search) to the extension. If the extension's service worker is sleeping, the first command automatically triggers a wake sequence, flipping the state from "disconnected" to "connected"【opencli.py†L12-L14】.

Detecting Session Availability

The opencli_status() function in agent_reach/backends/opencli.py probes the system to determine whether the Chrome session is reusable. It distinguishes between three distinct states based on daemon output and filesystem checks.

State 1: Extension Connected and Ready

When st.extension_connected returns True (parsed from daemon output), the extension is active and OpenCLI can immediately reuse the Chrome login session【opencli.py†L107-L112】. This state indicates that the service worker is awake and ready to proxy authenticated requests.

State 2: Installed but Sleeping

If st.extension_connected is False but _extension_installed_on_disk() returns True, the extension exists on disk but the service worker is inactive【opencli.py†L122-L125】. In this scenario, the first CLI command will wake the extension, enabling session reuse after the initial call completes.

State 3: Extension Not Installed

When _extension_installed_on_disk() returns False, the Chrome extension is missing entirely【opencli.py†L122-L126】. The system prompts users to install the extension from the Chrome Web Store before authenticated access is possible.

Implementation in Agent Reach Channels

The OpenCLISiteChannel class in agent_reach/channels/_opencli_site.py leverages these status checks to determine backend readiness. Its check() method evaluates the current state and returns appropriate hints for users when the extension is disconnected or missing【_opencli_site.py†L24-L48】.

This architecture ensures that OpenCLI does not store any credentials itself; it simply reads the cookies that Chrome already holds for the logged-in user, exposing them to downstream CLI tools as documented in docs/README_en.md【README_en.md†L73-L75】.

Practical Usage Examples

Query OpenCLI Status from Python

The following code demonstrates how Agent Reach probes the OpenCLI backend to verify session availability:

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, and returns an OpenCLIStatus object indicating whether the authenticated session is accessible【opencli.py†L80-L78】.

Execute Authenticated Commands via CLI

Once the extension is installed and you have logged into the target site in Chrome, reuse the session directly from the terminal:

# Search XiaoHongShu using existing Chrome authentication

opencli xiaohongshu search "AI agents" -f yaml

# Query Facebook with logged-in cookies

opencli facebook search "Machine Learning" -f yaml

# Retrieve Instagram user data

opencli instagram user "natgeo" -f yaml

The first call wakes a sleeping extension if necessary; subsequent calls reuse the already-connected session without additional latency.

Check Channel Health Programmatically

For custom implementations, verify channel readiness before executing commands:

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 a human-readable message based on whether the extension is installed, sleeping, or actively connected【_opencli_site.py†L28-L48】.

Summary

• OpenCLI reuses existing Chrome sessions by reading cookies from the browser rather than storing credentials independently.
• Three connection states determine availability: actively connected (ready), installed but sleeping (requires wake), and not installed (requires setup).
• Automatic wake behavior ensures that the first CLI command activates a sleeping extension, making subsequent calls immediate.
• Zero credential storage means sensitive authentication data remains within Chrome's secure cookie store, reducing exposure risks.
• Source files agent_reach/backends/opencli.py and agent_reach/channels/_opencli_site.py implement the probing logic and channel health checks.

Frequently Asked Questions

How does OpenCLI access Chrome cookies without storing passwords?

OpenCLI installs a browser extension (ID ildkmabpimmkaediidaifkhjpohdnifk) that reads cookies from Chrome's existing profile storage. The extension communicates with a local daemon that exposes these authenticated sessions to the CLI, meaning passwords never leave the browser environment or get stored in the OpenCLI configuration.

What happens if the Chrome extension is sleeping when I run a command?

If the extension's service worker is inactive, the first CLI command will automatically trigger a wake sequence. The daemon initially reports "Extension: disconnected" but flips to "connected" after the service worker initializes, allowing the command to proceed using your authenticated session.

Where is the OpenCLI extension installed on disk?

The extension resides within each Chrome profile directory at <profile>/Extensions/ildkmabpimmkaediidaifkhjpohdnifk/. The opencli.py backend verifies installation by checking this path using the _extension_installed_on_disk() function before attempting to communicate with the extension.

Can OpenCLI work with multiple Chrome profiles?

Yes, OpenCLI detects the extension within whichever Chrome profile it is installed. The path resolution logic in agent_reach/backends/opencli.py checks the standard Chrome profile directory structure, allowing users to maintain separate authenticated sessions across different browser profiles while using the same CLI interface.

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