How to Extract Browser Cookies for Multiple Platforms Using `agent-reach --from-browser`

Run agent-reach configure --from-browser <browser> to automatically import authentication cookies from Chrome, Firefox, Edge, Brave, or Opera into Agent-Reach's configuration for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.

Agent-Reach eliminates manual token management by extracting existing browser sessions directly from your local web browser. The --from-browser flag, implemented in the configure subcommand at agent_reach/cli.py, orchestrates a secure extraction process that maps browser cookies to platform-specific credentials without exposing sensitive data in shell history. This functionality supports Chromium-based browsers and Firefox, handling the complexity of cookie storage formats through robust abstraction layers.

How the --from-browser Architecture Works

The extraction flow involves four core components working sequentially from CLI input to persistent configuration.

CLI Argument Parsing

In agent_reach/cli.py (lines 86-90), the argument parser adds the --from-browser option to the configure subcommand. When invoked, the _cmd_configure handler detects args.from_browser and delegates to configure_from_browser.

Core Extraction Logic

The extract_all function in agent_reach/cookie_extract.py (line 42) serves as the primary extraction engine. It first attempts to import rookiepy (Rust-backed, preferred) and falls back to browser-cookie3 (pure-Python) if unavailable. The function calls browser-specific methods like rookiepy.chrome() or browser_cookie3.chrome() to obtain a cookie jar, then filters entries against the PLATFORM_SPECS declarative table (line 13). This table defines domain patterns and specific cookie names for each platform—for example, extracting auth_token and ct0 for Twitter/X while building complete header strings for XiaoHongShu.

Configuration Persistence

Extracted values flow into the Config class defined in agent_reach/config.py, which writes to ~/.agent-reach/config.yaml. The configure_from_browser function (line 32) handles this mapping, storing twitter_auth_token, twitter_ct0, xhs_cookie, bilibili_SESSDATA, and bilibili_bili_jct keys. It also performs legacy synchronization with ~/.config/xfetch/session.json and ~/.config/bird/credentials.env for backward compatibility.

Supported Browsers and Target Platforms

Agent-Reach accepts browser names case-insensitively and supports the same four platforms across all browsers:

• Chrome (default)
• Firefox
• Edge
• Brave
• Opera

Each browser populates credentials for:

• Twitter/X (extracts auth_token and ct0)
• XiaoHongShu (compiles full cookie string)
• Bilibili (extracts SESSDATA and bili_jct)
• Xueqiu (compiles full cookie string including xq_a_token)

Command-Line Usage Examples

Basic Chrome Extraction

Extract cookies from Chrome and persist them to Agent-Reach's configuration:

agent-reach configure --from-browser chrome

Typical output:

Extracting cookies from chrome...

  ✅ Twitter/X: auth_token + ct0
  ✅ XiaoHongShu: 12 cookies
  ✅ Bilibili: SESSDATA + bili_jct
  ✅ Xueqiu: 9 cookies (含 xq_a_token)

✅ Cookies configured! Run `agent-reach doctor` to see updated status.

Alternative Browser Selection

Use Firefox instead of Chrome:

agent-reach configure --from-browser firefox

The underlying extractor automatically calls rookiepy.firefox() or browser_cookie3.firefox() depending on available dependencies.

Verify Configuration

Confirm successful extraction and credential storage:

agent-reach doctor

This displays checkmarks (✅) next to each platform with valid credentials stored in ~/.agent-reach/config.yaml.

Programmatic Cookie Extraction

Import the extraction logic directly in Python for custom workflows:

from agent_reach.cookie_extract import extract_all

# Returns structured dict before YAML persistence

cookies = extract_all("chrome")
print(cookies)

Expected return structure:

{
    "twitter": {"auth_token": "AAA...", "ct0": "BBB..."},
    "xhs": {"cookie_string": "xhs_e=...; xhs_s=..."},
    "bilibili": {"SESSDATA": "CCC...", "bili_jct": "DDD..."},
    "xueqiu": {"cookie_string": "xq_a_token=...; other=..."}
}

Handling Missing Dependencies

If neither rookiepy nor browser-cookie3 is installed, the command aborts with explicit installation instructions:

Cookie extraction requires rookiepy or browser-cookie3.
Install: pip install rookiepy  (recommended)
     or: pip install browser-cookie3

rookiepy provides faster, more stable access to Chromium-based browser databases using Rust bindings, while browser-cookie3 offers broader compatibility as a pure-Python fallback. Both libraries are optional dependencies—you need only one installed for cookie extraction to function.

Summary

• agent-reach configure --from-browser <browser> imports existing browser sessions into Agent-Reach's YAML configuration.
• The extraction pipeline runs through extract_all in agent_reach/cookie_extract.py, filtering cookies against PLATFORM_SPECS for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• Rookiepy is the preferred extraction library, with browser-cookie3 serving as a fallback.
• Credentials persist to ~/.agent-reach/config.yaml and sync to legacy paths for backward compatibility.
• Verify successful extraction using agent-reach doctor.

Frequently Asked Questions

Which browsers does agent-reach --from-browser support?

The command supports Chrome, Firefox, Edge, Brave, and Opera. Browser names are case-insensitive, and each supports the same four platforms (Twitter/X, XiaoHongShu, Bilibili, Xueqiu). The underlying implementation in agent_reach/cookie_extract.py uses rookiepy or browser-cookie3 to read browser-specific storage formats.

What platforms can I authenticate using browser cookie extraction?

Agent-Reach extracts platform-specific credentials for Twitter/X (auth_token and ct0), XiaoHongShu (full cookie string), Bilibili (SESSDATA and bili_jct), and Xueqiu (full cookie string with xq_a_token). The PLATFORM_SPECS table in agent_reach/cookie_extract.py defines exactly which domains and cookie names map to each platform.

Why does the command fail with a dependency error?

Cookie extraction requires either rookiepy or browser-cookie3 installed in your Python environment. If neither is present, the CLI raises a clear error instructing you to run pip install rookiepy (recommended for performance) or pip install browser-cookie3 (pure-Python alternative). Both libraries read the browser's SQLite cookie databases, which Agent-Reach cannot access without these dependencies.

How do I verify that my cookies were extracted successfully?

Run agent-reach doctor after configuration. This command checks the ~/.agent-reach/config.yaml file (managed by the Config class) and displays a status table showing which platforms have valid credentials. Platforms with successfully extracted cookies show a green checkmark (✅), while missing credentials show an error indicator prompting re-extraction.

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