How Agent Reach Extracts Cookies from Chrome/Firefox Using `configure --from-browser`

Agent Reach's configure --from-browser command extracts authentication cookies from Chrome or Firefox by reading the browser's native SQLite databases via the rookiepy or browser-cookie3 libraries, then maps them to platform-specific configurations for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.

The agent-reach configure --from-browser command in the Panniantong/Agent-Reach repository provides a streamlined way to import browser cookies without manual copy-pasting. This functionality bridges the gap between your browser's secure cookie store and Agent Reach's configuration system, automatically extracting the specific authentication tokens required for each supported platform.

CLI Entry Point and Argument Parsing

The command-line interface is defined in agent_reach/cli.py, where the argparse definition adds the --from-browser flag with specific choices: chrome, firefox, edge, brave, and opera. When this flag is present, the _cmd_configure handler dispatches execution to the helper function configure_from_browser located in agent_reach/cookie_extract.py.

# Conceptual flow in cli.py

def _cmd_configure(args):
    if args.from_browser:
        configure_from_browser(args.from_browser, config)

The Cookie Extraction Pipeline

Library Selection and Fallback

The core extraction logic resides in agent_reach/cookie_extract.py. The extract_all(browser) function implements a priority-based library selection:

1. Primary: Attempts to import rookiepy, a Rust-based library that provides fast, direct access to browser cookie stores.
2. Fallback: If rookiepy is unavailable, falls back to browser-cookie3, a Python library with similar functionality.

The code invokes browser-specific functions such as rookiepy.chrome() or browser_cookie3.firefox() depending on which library is available.

Reading Encrypted and Plain SQLite Stores

Both rookiepy and browser-cookie3 read the native browser databases directly:

• On macOS and Windows, these databases are typically encrypted and require system keychain access to decrypt.
• On Linux, the SQLite files are usually stored in plain text.

Important: The browser process must be closed during extraction. If the browser is running, the database files are locked, and the function raises a descriptive error instructing the user to close the browser before retrying.

Platform-Specific Filtering with PLATFORM_SPECS

Agent Reach does not extract all cookies indiscriminately. Instead, it uses a global PLATFORM_SPECS list defined in agent_reach/cookie_extract.py (lines 15-42) to filter only relevant authentication tokens. Each spec defines:

• Domain patterns: Which domains to match (e.g., .twitter.com, .xueqiu.com)
• Cookie names: Either a specific list of required cookies (e.g., auth_token and ct0 for Twitter) or None to capture all cookies for that domain (e.g., XiaoHongShu)
• Config key: The internal identifier used to store the results (e.g., "twitter", "xhs")

The extraction loop iterates over raw cookie objects, keeping only those whose domain attribute ends with one of the spec's defined domains. When a spec lists concrete cookie names, only those specific values are extracted; when cookies is None, all matching cookies are concatenated into a single header string.

Mapping Cookies to Configuration

Once configure_from_browser returns a dictionary keyed by platform identifiers, the _cmd_configure function in agent_reach/cli.py persists the values to Agent Reach's configuration store (config.set()):

• Twitter/X: Extracts auth_token and ct0, storing them as twitter_auth_token and twitter_ct0 respectively.
• XiaoHongShu: Stores the full concatenated cookie string as xhs_cookie.
• Bilibili: Saves SESSDATA as bilibili_sessdata and bili_jct (if present) as bilibili_csrf.
• Xueqiu: Stores the full cookie header only if the mandatory xq_a_token is present in the extracted data.

The CLI prints a success or failure line for each platform, giving immediate visibility into which authentication cookies were successfully imported.

Legacy Tool Synchronization

For Twitter specifically, the extraction routine includes legacy compatibility helpers. The function _sync_xfetch_session and _sync_bird_env (lines 51-73 in cookie_extract.py) synchronize the extracted Twitter credentials to older companion tools (xfetch and bird), ensuring backward compatibility with existing workflows.

Summary

• The configure --from-browser command is a thin wrapper around agent_reach/cookie_extract.py.
• It uses rookiepy (preferred) or browser-cookie3 (fallback) to read browser SQLite databases.
• The browser must be closed during extraction to avoid database lock conflicts.
• PLATFORM_SPECS filters raw cookies by domain and name for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• Extracted values are mapped to config keys like twitter_auth_token, xhs_cookie, and bilibili_sessdata.
• Legacy sync helpers maintain compatibility with xfetch and bird tools for Twitter data.

Frequently Asked Questions

What browsers are supported by Agent Reach's cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The CLI validates the browser name against these choices before attempting extraction.

Why does the browser need to be closed during extraction?

The cookie databases are locked by the browser process while it is running. Attempting to read these files while the browser is active triggers a file lock error, so the extraction engine requires the browser to be fully closed to ensure safe read access to the SQLite stores.

What happens if rookiepy is not installed?

If rookiepy is unavailable, the system automatically falls back to browser-cookie3. This fallback is implemented in agent_reach/cookie_extract.py (lines 99-108), ensuring the command works regardless of which library is present in the environment.

Which specific cookies are extracted for Twitter/X authentication?

For Twitter/X, the system specifically targets the auth_token and ct0 cookies. These are stored separately in the configuration as twitter_auth_token and twitter_ct0, which are the mandatory credentials required for API access.

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