# How to Troubleshoot OpenCLI Extension Installation for Browser Session Reuse in Agent-Reach

> Troubleshoot OpenCLI extension installation for Agent-Reach browser session reuse. Use agent-reach doctor and npm to diagnose and repair issues for seamless integration.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-13

---

**The OpenCLI backend requires three components—the CLI tool, background daemon, and Chrome extension—to be fully installed and running before Agent-Reach can reuse your desktop browser sessions; diagnose failures using `agent-reach doctor --json` and repair missing pieces with npm and the Chrome Web Store.**

Agent-Reach relies on the OpenCLI backend to bridge the gap between its automation agents and your existing Chrome login sessions. When properly configured, this system allows the agent to read authenticated data from platforms like Reddit, XiaoHongShu, Facebook, and Instagram without requiring separate credentials. If any component of the OpenCLI stack fails, the system reports specific error states that you can troubleshoot using built-in diagnostic commands.

## Understanding the OpenCLI Architecture

The OpenCLI integration consists of three distinct parts that must all function together to enable browser session reuse.

### The Three Required Components

| Component | Purpose | Location |
| --- | --- | --- |
| **OpenCLI command-line tool** | A Node-based CLI (`opencli`) that communicates with the daemon | [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) |
| **OpenCLI daemon** | A local background process that forwards commands from the CLI to Chrome | Same file—queried via `opencli daemon status` |
| **Chrome extension** | Browser-side bridge (ID `ildkmabpimmkaediidaifkhjpohdnifk`) that exposes logged-in cookies to the daemon | `OPENCLI_EXTENSION_ID` constant in [`opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/opencli.py) |

If any of these pieces is missing or misconfigured, the backend reports "OpenCLI …" errors and Agent-Reach cannot access platforms requiring authenticated sessions.

## Diagnosing OpenCLI Installation Issues

Start troubleshooting by checking the current state of all three components using the built-in diagnostic tools.

### Check Backend Status with Agent-Reach Doctor

Run the comprehensive health check to get JSON output that is easier to parse:

```bash
agent-reach doctor --json

```

The JSON output contains an `opencli` entry with fields `installed`, `daemon_running`, `extension_connected`, and `extension_installed`. Interpret the results as follows:

- **If `installed` is false**: The `opencli` binary is not on your PATH.
- **If `daemon_running` is false**: The background daemon is not active.
- **If `extension_connected` is false but `extension_installed` is true**: The extension is sleeping and will wake on the next real command.
- **If both extension fields are false**: The Chrome extension is completely missing from your browser.

You can also query the daemon directly without side effects:

```bash
opencli doctor
opencli daemon status

```

These commands are wrapped in the `opencli_status()` function (lines 80–122 of [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py)).

### Verify the CLI Tool Installation

Confirm the binary exists and is executable:

```bash
opencli --version

```

If the command returns "command not found", install the tool globally using npm:

```bash
npm install -g @jackwener/opencli

```

This installation routine is referenced in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 752–801). If the command exists but returns a runtime error, the `OpenCLIStatus` object marks the installation as `broken` and displays the hint to reinstall the npm package.

### Confirm Chrome Extension Presence

The helper `_extension_installed_on_disk()` (lines 40–55 of [`opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/opencli.py)) scans typical Chrome profile directories for the folder `…/Extensions/ildkmabpimmkaediidaifkhjpohdnifk`.

To manually verify:

1. Open Chrome and navigate to `chrome://extensions/`.
2. Verify that **OpenCLI** is listed and enabled.
3. If missing, install it from the Chrome Web Store: `https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk`.

The `hint` field in `OpenCLIStatus` (lines 16–20) contains a ready-to-copy message with this URL.

## Fixing Common OpenCLI Installation Problems

Once you have identified the missing component, follow these specific repair steps.

### Install the Missing CLI Tool

If `agent-reach doctor` reports `installed: false`, run:

```bash
npm install -g @jackwener/opencli

```

After installation, verify with `opencli --version` and rerun `agent-reach doctor --json`.

### Install or Repair the Chrome Extension

If the extension is missing or disabled:

1. Visit `https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk`.
2. Click **Add to Chrome**.
3. Ensure Chrome remains open while running your first `opencli` command, as this wakes the service worker (see comments in lines 12–14 of the backend source).

### Restart the Daemon and Wake the Extension

If the daemon reports "Extension: disconnected" even after installation:

```bash

# Stop and restart the daemon

opencli daemon stop
opencli daemon start

# Force a wake-up call

opencli doctor

```

If the daemon still fails to connect, reinstall the extension from the store and run `opencli doctor` again to verify the connection.

## Environment Limitations and Alternatives

OpenCLI works **only on desktop environments** with a real Chrome instance. When the installer runs on a headless server, the `install` command automatically skips OpenCLI-only channels, as defined in `server_skipped_opencli_channels` (lines 30–35 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)).

If you attempted a server install but need OpenCLI functionality, migrate to a local machine or use alternative back-ends such as `rdt-cli` for Reddit-specific access.

## Summary

- **OpenCLI requires three components**: the npm CLI tool (`@jackwener/opencli`), the background daemon, and the Chrome extension (ID `ildkmabpimmkaediidaifkhjpohdnifk`).
- **Diagnose with**: `agent-reach doctor --json` or `opencli daemon status` to check `installed`, `daemon_running`, and `extension_connected` states.
- **Install CLI with**: `npm install -g @jackwener/opencli` when the binary is missing or broken.
- **Install extension from**: the Chrome Web Store using the specific URL stored in the `hint` field of `OpenCLIStatus`.
- **Wake sleeping extensions** by running `opencli doctor` while Chrome is open.
- **Desktop-only**: OpenCLI does not function on headless servers; use alternative back-ends for server environments.

## Frequently Asked Questions

### Why does OpenCLI say "Extension: disconnected" even after I installed it?

The extension enters a sleep state when idle to save resources. Run `opencli doctor` while Chrome is open to trigger the service worker wake-up. If it remains disconnected, reinstall the extension from the Chrome Web Store and restart the daemon with `opencli daemon stop` followed by `opencli daemon start`.

### Can I use OpenCLI on a headless server or Docker container?

No. OpenCLI requires a desktop Chrome instance with a user profile to access cookies. According to the `server_skipped_opencli_channels` logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 30–35), the installer automatically skips OpenCLI-dependent channels on headless servers. You must run Agent-Reach on a local machine with a GUI to use this feature.

### Which platforms require OpenCLI in Agent-Reach?

The OpenCLI backend is required for platforms that rely on existing browser authentication, including Reddit, XiaoHongShu, Facebook, and Instagram. These are defined in the skill configuration at [`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/SKILL.md). Without OpenCLI, Agent-Reach cannot read data from these platforms unless you configure alternative authentication methods.

### How do I verify the extension is installed in the correct Chrome profile?

The `_extension_installed_on_disk()` function (lines 40–55 of [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py)) scans standard Chrome profile directories for the folder `ildkmabpimmkaediidaifkhjpohdnifk`. To verify manually, open `chrome://extensions/` in every Chrome profile you use, ensure the extension is enabled, and check that the ID matches exactly. The extension must be installed in the same profile that contains your logged-in sessions for the target platforms.