How Agent Reach Extracts Browser Cookies for Platform Authentication

Agent Reach extracts authentication cookies from Chrome, Firefox, Edge, Brave, and Opera using a dual-library approach (primary rookiepy with browser_cookie3 fallback) to enable authenticated API access across Twitter, XiaoHongShu, Bilibili, and Xueqiu.

The Agent Reach repository provides a cross-platform solution for automating social media interactions, requiring valid session cookies to authenticate as a logged-in user. Browser cookie extraction for platform authentication is handled entirely within the agent_reach/cookie_extract.py module, which provides both programmatic APIs and CLI integration. This self-contained pipeline normalizes cookies from different browsers, matches them against platform-specific domain patterns, and persists them to the user's configuration file.

The Extraction Pipeline

The cookie extraction workflow follows a clear sequence: detect the browser, load the cookie store, normalize the objects, filter by domain and name, and format the output for each platform's requirements.

Supported Browsers and Libraries

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera through a resilient dual-library strategy. The code first attempts to use the Rust-based rookiepy library for stability, falling back to the pure-Python browser_cookie3 when rookiepy is unavailable.

# Lines 58-66 in agent_reach/cookie_extract.py

try:
    import rookiepy
    # Use rookiepy for extraction...

except ImportError:
    import browser_cookie3 as bc3
    # Fallback to browser_cookie3...

This conditional import ensures the tool functions across different environments without forcing a specific dependency stack.

Platform Specifications

A centralized PLATFORM_SPECS table (lines 15-40 in cookie_extract.py) defines the exact cookie requirements for each supported platform:

• Twitter: Requires auth_token and ct0 cookies
• XiaoHongShu (XHS): Collects all cookies as a semicolon-separated header string
• Bilibili: Extracts SESSDATA and optionally bili_jct
• Xueqiu: Captures the entire domain's cookie set but only stores if xq_a_token is present

Each specification includes the target domains and cookie names necessary for authentication.

Cookie Collection and Normalization

After loading the appropriate browser function (browser_funcs[browser]()), the returned cookie objects are wrapped in a minimal _Cookie class when using rookiepy. This normalization step (lines 77-95) ensures consistent access to name, value, and domain attributes regardless of the underlying library.

# Conceptual usage from the source

from agent_reach.cookie_extract import extract_all

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

# {'twitter': {'auth_token': '...', 'ct0': '...'}, 

#  'xhs': {'cookie_string': '...'}, ...}

Filtering and Formatting Logic

The extraction engine iterates over collected cookies and applies platform-specific filters (lines 118-147). For each platform spec, it selects cookies matching the defined domains, then either builds a dictionary of named cookies or assembles a semicolon-separated header string (; name=value) for platforms requiring full cookie strings.

Configuration and Storage

Once extracted, the authentication data must persist securely and remain accessible to channel implementations.

CLI Integration

The configure_from_browser() function writes extracted values into the central Config object via config.set(). This process is triggered automatically during installation when cookie-requiring channels are requested, or manually via CLI commands.

Automatic extraction during installation:

agent-reach install --channels twitter,xueqiu

# Outputs: "Importing cookies from browser…"

# Stores tokens in ~/.agent-reach/config.yaml

Manual extraction for a specific browser:

agent-reach configure --from-browser firefox

# Prints: "✅ Twitter/X: auth_token + ct0"

The CLI integration spans lines 71-80 in agent_reach/cli.py for the auto-import block and lines 81-90 for the configure sub-parser definition.

Legacy Compatibility

For backward compatibility with previous tooling, configure_from_browser() synchronizes legacy files used by the former xfetch and bird CLIs. The _sync_xfetch_session and _sync_bird_env functions (lines 44-90 and 118-150 in cookie_extract.py) ensure that extracted Twitter credentials also populate legacy credential stores.

Summary

• Dual-library support: Uses rookiepy primarily with browser_cookie3 fallback to ensure cross-platform compatibility.
• Platform-specific filtering: The PLATFORM_SPECS table defines exact cookie names and domain patterns for Twitter, XiaoHongShu, Bilibili, and Xueqiu.
• Normalization layer: The _Cookie class standardizes cookie attributes regardless of the extraction library used.
• Flexible output: Returns either named cookie dictionaries or semicolon-separated header strings based on platform requirements.
• Integrated persistence: Automatically saves to ~/.agent-reach/config.yaml while maintaining legacy sync for existing CLI tools.

Frequently Asked Questions

Which browsers does Agent Reach support for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The system detects the browser's cookie store location automatically and uses appropriate extraction methods for each.

How does Agent Reach handle missing cookie extraction dependencies?

The code implements a graceful fallback strategy. It first attempts to import rookiepy (a Rust-based library offering better stability), and if unavailable, falls back to the pure-Python browser_cookie3 library. This ensures the tool works on any platform without forcing specific dependency installations.

What platforms are supported by the cookie extraction system?

The system supports Twitter (requiring auth_token and ct0), XiaoHongShu (full cookie string), Bilibili (SESSDATA and optionally bili_jct), and Xueqiu (domain cookies with xq_a_token validation). Each platform has specific domain patterns and cookie name requirements defined in the PLATFORM_SPECS table.

Where are the extracted cookies stored after extraction?

Extracted cookies are stored in the user's ~/.agent-reach/config.yaml file via the Config object. For Twitter specifically, the system also writes to legacy credential files used by the xfetch and bird CLI tools to maintain backward compatibility with existing workflows.

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