Cookie Extraction Process for Different Browsers in Agent Reach: A Complete Technical Guide

Agent Reach extracts authentication cookies from Chrome, Firefox, Edge, Brave, and Opera using a dual-backend system that prioritizes the Rust-based rookiepy library and falls back to browser_cookie3, filtering retrieved data against platform-specific domain rules to return normalized cookie dictionaries for supported social media platforms.

The cookie extraction process in the Panniantong/Agent-Reach repository automates authentication for platforms like Twitter/X, XiaoHongShu, Bilibili, and Xueqiu by reading SQLite cookie stores directly from your local browser profiles. This functionality is encapsulated in agent_reach/cookie_extract.py and implements a robust pipeline that handles backend abstraction, data normalization, and platform-specific filtering without requiring manual cookie copying.

How Agent Reach Extracts Browser Cookies: The 7-Step Process

The extraction flow follows a deterministic pipeline from backend selection to configuration persistence. Each step is designed to handle variations in browser storage formats while maintaining security and accuracy.

1. Backend Selection: rookiepy vs browser_cookie3

The module first attempts to import rookiepy, a high-performance Rust-based cookie scraper. If unavailable, it gracefully falls back to browser_cookie3, a pure-Python alternative. Both libraries understand how to locate browser profile directories and parse their SQLite cookie databases, but rookiepy is preferred for its speed and tolerance of platform-specific edge cases.

In agent_reach/cookie_extract.py (lines 55-62), the selection logic appears as:

try:
    import rookiepy
    BACKEND = "rookiepy"
except ImportError:
    import browser_cookie3
    BACKEND = "browser_cookie3"

2. Browser Validation and Normalization

Before accessing any files, the code validates the requested browser name against a strict allowlist. The caller provides a name (chrome, firefox, edge, brave, opera), which is lower-cased and checked against the supported list. An invalid name immediately raises a ValueError to prevent filesystem errors.

From agent_reach/cookie_extract.py (lines 68-73):

supported = ["chrome", "firefox", "edge", "brave", "opera"]
browser = browser.lower().strip()
if browser not in supported:
    raise ValueError(f"Unsupported browser: {browser}. Choose from {supported}")

3. Raw Cookie Retrieval from SQLite Stores

Once validated, the code invokes the appropriate backend function (e.g., rookiepy.chrome or browser_cookie3.chrome) to read the browser’s SQLite cookie store. The returned objects are immediately normalized into a lightweight _Cookie class that exposes uniform .name, .value, and .domain attributes, abstracting away differences between backend data structures.

The retrieval and normalization occurs in agent_reach/cookie_extract.py (lines 78-92):

browser_funcs = {
    "chrome": rookiepy.chrome if BACKEND == "rookiepy" else browser_cookie3.chrome,
    "firefox": rookiepy.firefox if BACKEND == "rookiepy" else browser_cookie3.firefox,
    # ... edge, brave, opera mappings

}
raw_cookies = browser_funcs[browser]()
cookie_jar = [_Cookie(c) for c in raw_cookies]

4. Platform Specification Mapping

Agent Reach uses a constant table called PLATFORM_SPECS (defined at lines 13-38) that declaratively defines each supported platform’s domain patterns and required cookie names. This configuration separates platform requirements from extraction logic, making it trivial to add new services.

Each entry specifies:

• Domain patterns: List of domains to match (e.g., .x.com, .twitter.com)
• Cookie names: Specific cookies to extract (e.g., auth_token, ct0) or None to capture all cookies for the domain

PLATFORM_SPECS = [
    {
        "name": "Twitter/X",
        "config_key": "twitter",
        "domains": [".x.com", ".twitter.com"],
        "cookies": ["auth_token", "ct0"]
    },
    {
        "name": "XiaoHongShu",
        "config_key": "xhs",
        "domains": [".xiaohongshu.com"],
        "cookies": None  # Capture all cookies

    },
    # ... Bilibili, Xueqiu entries

]

5. Domain Filtering and Aggregation

The extraction engine iterates over every cookie in the normalized jar, matching its domain against each platform’s domains list. When cookies is None, it aggregates all matching cookies into a header-style string ("name=value; name2=value2"). When specific names are required, it builds a dictionary mapping cookie names to values.

This logic appears in agent_reach/cookie_extract.py (lines 31-44):

for spec in PLATFORM_SPECS:
    domain_cookies = [c for c in cookie_jar if any(c.domain.endswith(d) for d in spec["domains"])]
    
    if spec["cookies"] is None:
        # Aggregate all cookies into a single string

        cookie_str = "; ".join(f"{c.name}={c.value}" for c in domain_cookies)
        results[spec["config_key"]] = {"cookie_string": cookie_str}
    else:
        # Extract specific named cookies

        name_map = {c.name: c.value for c in domain_cookies}
        results[spec["config_key"]] = {k: name_map[k] for k in spec["cookies"] if k in name_map}

6. Result Normalization and Return

The function returns a dictionary keyed by each platform’s config_key (e.g., "twitter", "xhs", "bilibili"). Each value contains either a mapping of specific cookie names to values, or a single cookie_string field containing the serialized header format required by that platform’s API.

7. CLI Integration and Configuration Persistence

The high-level helper configure_from_browser() (defined in the same file) orchestrates the extraction and persists results to ~/.agent-reach. It calls extract_all(), writes discovered cookies into the user’s configuration object, and optionally syncs Twitter credentials to legacy tooling.

From agent_reach/cookie_extract.py:

def configure_from_browser(browser: str, config: Config) -> List[Tuple[str, bool, str]]:
    extracted = extract_all(browser)
    for platform, data in extracted.items():
        config.set(f"cookies.{platform}", data)
    return summary  # Returns status tuples for CLI display

Supported Browsers and Requirements

Agent Reach officially supports Chrome, Firefox, Edge, Brave, and Opera. For successful extraction:

• The browser must be closed during extraction to avoid SQLite file locking
• The user must have read permissions on the browser’s profile directory (typically ~/.config/google-chrome/ on Linux, %LOCALAPPDATA%\Google\Chrome\User Data\ on Windows, or ~/Library/Application Support/Google/Chrome/ on macOS)
• The target platforms must have active login sessions stored in the browser

Backend Comparison: Why Two Libraries?

rookiepy is the primary backend because it is a compiled Rust library that handles platform-specific edge cases more robustly than pure-Python alternatives. It offers better performance and is less likely to fail on corrupted or locked cookie stores.

browser_cookie3 serves as the fallback when rookiepy is not installed. While it works across all major operating systems, it may be slower and less tolerant of malformed SQLite databases. If neither library is available, the code raises a RuntimeError instructing the user to install one via pip install rookiepy or pip install browser-cookie3.

Error Handling and Edge Cases

The extraction layer wraps individual read failures (such as when the browser is still running) in RuntimeError with actionable hints. File permission errors are handled gracefully, and the test suite in tests/test_cookie_extract_perms.py verifies that the code respects OS-level security by ensuring it only reads from owner-only directories.

Practical Implementation Examples

Programmatic Cookie Extraction

Extract cookies from Chrome for use in automation scripts:

from agent_reach.cookie_extract import extract_all

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

# Example output:

# {

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

#   "xhs": {"cookie_string": "sessionid=...; other=..."},

#   "bilibili": {"SESSDATA": "...", "bili_jct": "..."},

#   "xueqiu": {"cookie_string": "xq_a_token=...; ..."}

# }

CLI Configuration

Automatically configure Agent Reach from the command line:

agent-reach configure --from-browser chrome

# Output:

#   Twitter/X  ✓  auth_token + ct0

#   XiaoHongShu  ✓  3 cookies

#   Bilibili  ✓  SESSDATA + bili_jct

#   Xueqiu  ✓  5 cookies (含 xq_a_token)

Integration with Config Object

Use the high-level helper to extract and persist cookies in Python applications:

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

cfg = Config()
summary = configure_from_browser("firefox", cfg)
for platform, ok, msg in summary:
    print(f"{platform}: {'✓' if ok else '✗'} {msg}")

Summary

• Agent Reach uses a dual-backend architecture (rookiepy preferred, browser_cookie3 fallback) to extract cookies from Chrome, Firefox, Edge, Brave, and Opera.
• The extraction pipeline is implemented in agent_reach/cookie_extract.py and follows seven distinct steps from backend selection to result normalization.
• PLATFORM_SPECS defines platform requirements (domain patterns and cookie names) declaratively, supporting Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• Cookies are normalized into a _Cookie class and filtered by domain, returning either specific name-value mappings or aggregated header strings.
• The configure_from_browser() function bridges extraction and persistence, writing results to ~/.agent-reach via agent_reach/config.py.
• Browsers must be closed during extraction, and the system requires appropriate file permissions to read SQLite cookie stores.

Frequently Asked Questions

Which browsers does Agent Reach support for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The system normalizes these browser names and validates them against an internal allowlist before attempting to read their SQLite cookie stores. Both rookiepy and browser_cookie3 backends support these five browsers across Windows, macOS, and Linux.

What should I do if cookie extraction fails with a "browser is running" error?

Close the browser completely before extraction. The cookie extraction process requires exclusive access to the browser’s SQLite database files, which are locked while the browser is running. If the error persists, ensure no background browser processes remain active in your system’s task manager or activity monitor.

How does Agent Reach handle cookie format differences between platforms?

The PLATFORM_SPECS configuration in agent_reach/cookie_extract.py defines whether a platform requires specific named cookies (like auth_token and ct0 for Twitter) or a complete cookie header string (like XiaoHongShu). The extraction logic branches based on the cookies field: when None, it aggregates all domain cookies into a semicolon-separated string; otherwise, it extracts only the named cookies into a dictionary.

Can I use extracted cookies programmatically without the CLI?

Yes. Import extract_all() from agent_reach/cookie_extract and call it with a browser name string (e.g., "chrome"). This returns a dictionary of platform configurations ready for use with HTTP clients. For automatic persistence, use configure_from_browser(), which accepts a Config object and writes the extracted data to your ~/.agent-reach configuration file.

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