How the Cookie Extraction Module Parses Browser Data in Agent-Reach

The cookie extraction module in Agent-Reach uses a dual-library extraction strategy to pull browser cookies, filter them by platform-specific domain patterns, and convert them into either structured dictionaries or header-style strings for authentication.

Agent-Reach is an open-source automation framework that streamlines browser-based authentication for social media platforms. The agent_reach/cookie_extract.py module serves as the central component for harvesting and normalizing browser cookies into the exact key-value structures required by various platform channels. This self-contained module handles everything from low-level browser database access to high-level configuration persistence.

Dual-Layer Extraction Strategy

The module implements a robust fallback mechanism to ensure cross-platform compatibility across different browser installations.

Primary Rust-Based Extraction with rookiepy

At agent_reach/cookie_extract.py#L55-L67, the code first attempts to use the Rust-based rookiepy library. This provides faster, more stable access to browser cookie stores across Chrome, Firefox, Edge, Brave, and Opera. The primary extraction path offers better performance when handling large browser databases or encryptedcookie stores.

Fallback to Pure-Python browser_cookie3

If rookiepy fails or is unavailable, the module falls back to the pure-Python browser_cookie3 package. Each supported browser maps to a corresponding callable (e.g., browser_cookie3.chrome), returning a CookieJar of http.cookiejar.Cookie objects at agent_reach/cookie_extract.py#L102-L106. This ensures the module remains functional even when Rust dependencies are not installed.

Platform-Specific Cookie Specifications

Before filtering, the module defines platform requirements in the PLATFORMS list at agent_reach/cookie_extract.py#L15-L28. Each specification includes the target domain pattern, the configuration key for storage, and optionally a list of required cookie names.

Structured Requirements vs. Header Strings

For Twitter, the specification requires specific cookie names (auth_token and ct0). For XiaoHongShu, the module grabs all cookies and concatenates them into a single header-style string. This distinction determines whether the output becomes a dictionary or a semicolon-delimited string.

The Cookie Processing Pipeline

The extraction process follows four distinct phases implemented in extract_cookies().

Step 1: Raw Cookie Normalization

Raw browser cookies are wrapped in a private _Cookie dataclass at agent_reach/cookie_extract.py#L94-L98. This helper class retains only the name, value, and domain fields needed for downstream matching, discarding unnecessary attributes like expiration dates or path specifications.

Step 2: Domain-Based Filtering

The module iterates over extracted cookies and checks domain patterns using the logic cookie.domain.endswith(d) or cookie.domain == d.lstrip(".") at agent_reach/cookie_extract.py#L122-L125. Matching cookies accumulate in all_cookies_for_domain, ensuring only relevant authentication tokens for the target platform are retained.

Step 3: Payload Construction

At agent_reach/cookie_extract.py#L131-L141, the code branches based on the platform specification. If spec["cookies"] is a list, it builds a dictionary of whitelisted names. If None, it joins all cookies into a header-style string using name=value; formatting. This dual-output approach accommodates different authentication mechanisms across platforms.

Configuration Persistence

The high-level helper configure_from_browser() at agent_reach/cookie_extract.py#L260-L284 handles the final storage phase. It writes extracted strings into the Agent-Reach config file using config.set(), performing sanity checks such as verifying Xueqiu cookies contain xq_a_token before persistence. This prevents invalid or incomplete authentication data from being saved to the user's configuration.

Practical Usage Examples

Extract and configure via the CLI:

python -m agent_reach.cli install --env=local

# Output:

#   Importing cookies from browser...

#   Extracting cookies from chrome...

#   ✅ Twitter (2 cookies)

#   ✅ XiaoHongShu (5 cookies)

Programmatic extraction without modifying global config:

from agent_reach.cookie_extract import extract_cookies

# Extract from specific browser

raw = extract_cookies(browser="chrome")
print(raw["twitter"]["auth_token"])  # Access specific token

Persist to configuration for later use:

from agent_reach.cookie_extract import configure_from_browser
from agent_reach.config import config

configure_from_browser(browser="firefox")

# Read back via Config API

print(config.get("twitter_cookie"))  # "auth_token=...; ct0=..."

Consuming cookies in a channel implementation:

from agent_reach.config import config
from agent_reach.channels.twitter import TwitterChannel

cookies = {
    "auth_token": config.get("twitter_auth_token"),
    "ct0": config.get("twitter_ct0")
}
twitter = TwitterChannel(cookies=cookies)

Summary

• The module uses a dual-library strategy (rookiepy → browser_cookie3) for maximum compatibility across different system configurations
• Platform specifications in PLATFORMS define domain patterns and required cookie names at agent_reach/cookie_extract.py#L15-L28
• Domain-based filtering matches cookies using flexible suffix and equality checks against platform target domains
• Output formats vary between structured dictionaries (for specific token requirements) and header-style strings (for bulk cookie injection)
• The configure_from_browser() helper persists validated cookies to the YAML config store after performing platform-specific sanity checks

Frequently Asked Questions

Which browsers does the cookie extraction module support?

The module supports Chrome, Firefox, Edge, Brave, and Opera through both the rookiepy and browser_cookie3 backends, as mapped in the extraction logic at agent_reach/cookie_extract.py#L102-L106. The dual-library approach ensures compatibility even if one backend fails to read a particular browser's encryption or storage format.

What happens if both rookiepy and browser_cookie3 fail?

If neither library can access the browser cookie store, the extract_cookies() function returns an empty dictionary or raises an exception depending on the specific error. This prevents partial or corrupted configuration data from being saved to the Agent-Reach config file.

How does Agent-Reach handle cookies for platforms requiring specific tokens versus all cookies?

Platforms like Twitter require specific named cookies (auth_token, ct0) and receive a filtered dictionary, while platforms like XiaoHongShu receive all matching domain cookies concatenated into a single name=value; header string. This logic branches at agent_reach/cookie_extract.py#L131-L141 based on whether spec["cookies"] is a list or None.

Where are the extracted cookies stored after extraction?

The configure_from_browser() function persists cookies to Agent-Reach's YAML-based configuration file using the config.set() method, storing them under platform-specific keys like twitter_cookie or xhs_cookie at agent_reach/cookie_extract.py#L260-L284. The module validates cookies (such as checking for xq_a_token in Xueqiu cookies) before writing to disk.

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