How Agent Reach Extracts Cookies from Chrome, Firefox, and Edge

Agent Reach extracts cookies from Chrome, Firefox, and Edge by delegating to the Rust-based rookiepy library (falling back to browser_cookie3 if unavailable), then filters the retrieved data against platform-specific specifications to isolate authentication tokens for supported services like Twitter/X, XiaoHongShu, and Bilibili.

Agent Reach is an open-source automation framework that simplifies browser authentication by programmatically harvesting session cookies from local browser storage. The extraction logic resides primarily in agent_reach/cookie_extract.py, which implements a dual-library strategy to ensure cross-platform compatibility while maintaining specific domain and cookie name filters for each supported platform.

Supported Browsers and Fallback Strategy

The core extraction routine in agent_reach/cookie_extract.py supports five major browsers: Chrome, Firefox, Edge, Brave, and Opera. The implementation maintains a prioritized list of third-party libraries to maximize reliability, as shown in lines 53-66:

1. rookiepy – A Rust-based library serving as the primary extraction engine
2. browser_cookie3 – A pure Python fallback used when rookiepy is unavailable

The code attempts to import rookiepy first, catching ImportError to trigger the fallback mechanism. If neither library loads successfully, the system raises a clear runtime exception.

# From agent_reach/cookie_extract.py

supported = ["chrome", "firefox", "edge", "brave", "opera"]

When a caller requests a browser not present in this supported list, the function raises a ValueError immediately (lines 68-73), preventing invalid state downstream.

Platform-Specific Cookie Specifications

Before extraction begins, Agent Reach references the PLATFORM_SPECS constant (defined in lines 14-39 of agent_reach/cookie_extract.py) to determine exactly which cookies to retrieve for each automation target. This specification maps platforms to their required domains and cookie names:

• Twitter/X – Searches for auth_token and ct0 cookies under .x.com or .twitter.com
• XiaoHongShu – Captures all cookies for .xiaohongshu.com, returning them as a concatenated header string
• Bilibili – Extracts SESSDATA and bili_jct specifically for .bilibili.com

These specifications ensure that only authentication-relevant cookies are extracted, ignoring session data for unrelated services.

Extraction Implementation: rookiepy vs browser_cookie3

The extraction path diverges based on which library successfully imports, though both ultimately yield browser-specific cookie data through dynamic function mapping in browser_funcs.

rookiepy Integration

When available, rookiepy provides cookie data as a list of dictionaries containing name, value, domain, and other standard fields. Agent Reach wraps each dictionary in a private _Cookie class (lines 75-92) that exposes .name, .value, and .domain attributes for uniform access:

# Conceptual implementation from agent_reach/cookie_extract.py

class _Cookie:
    def __init__(self, data):
        self.name = data["name"]
        self.value = data["value"]
        self.domain = data["domain"]

browser_cookie3 Fallback

If rookiepy is unavailable, the system uses browser_cookie3, which returns CookieJar-compatible objects (lines 98-100) that already implement the required attribute interface. These objects are passed directly to the filtering stage without transformation.

The selected browser function (e.g., chrome(), firefox(), or edge()) is invoked dynamically from the browser_funcs mapping, with results stored in a cookie_jar iterable for processing.

Filtering and Formatting Logic

Once raw cookies are retrieved, Agent Reach applies strict filtering to match the PLATFORM_SPECS definitions. The filtering logic in lines 120-124 validates domain matches using suffix and equality checks:

# Domain matching logic from agent_reach/cookie_extract.py

if cookie.domain.endswith(d) or cookie.domain == d.lstrip("."):
    # Process matching cookie

For platforms specifying exact cookie names (like Twitter/X), only cookies matching those specific names are retained. For platforms like XiaoHongShu where spec["cookies"] is None, all cookies for the matching domain are concatenated into a single header string using "; ".join(f"{c.name}={c.value}" for c in all_cookies_for_domain) (lines 135-141).

The final output is a dictionary keyed by platform identifiers (e.g., "twitter", "xhs"), ready for configuration storage.

CLI Integration

Agent Reach exposes this functionality through the command line interface defined in agent_reach/cli.py. The agent-reach configure --from-browser <browser> command triggers the extraction pipeline through the configure_from_browser function:

# Extract from Chrome and auto-populate configuration

agent-reach configure --from-browser chrome

# Preview extraction without modifying config

agent-reach configure --from-browser chrome --dry-run

The CLI imports configure_from_browser from cookie_extract.py (lines 284-307), executes the extraction, and prints status messages indicating which platforms were successfully configured.

Storing the Cookies

After successful extraction, the configure_from_browser helper writes each platform's cookie data into the centralized configuration via config.set() (implemented in agent_reach/config.py). For example, XiaoHongShu's concatenated cookie string is stored under the key xhs_cookie (lines 266-271), while individual Twitter tokens populate twitter_auth_token and twitter_ct0 entries.

Summary

• Agent Reach extracts cookies from Chrome, Firefox, and Edge using rookiepy as the primary engine, with browser_cookie3 as a fallback
• The PLATFORM_SPECS constant in agent_reach/cookie_extract.py defines which domains and cookie names to target for each supported platform
• Raw cookies are filtered using domain suffix matching (cookie.domain.endswith(d)) and exact equality checks (cookie.domain == d.lstrip(".")) before being formatted into configuration-ready dictionaries
• The agent-reach configure --from-browser CLI command provides easy access to the extraction functionality
• Extracted data is persisted via config.set() in agent_reach/config.py using platform-specific keys like xhs_cookie and twitter_auth_token

Frequently Asked Questions

Does Agent Reach support browsers other than Chrome, Firefox, and Edge?

Yes. In addition to Chrome, Firefox, and Edge, Agent Reach supports Brave and Opera through the same extraction mechanism. The supported list in agent_reach/cookie_extract.py explicitly includes these browsers, and the underlying libraries (rookiepy and browser_cookie3) provide dedicated functions for each.

What happens if neither rookiepy nor browser_cookie3 is installed?

If both libraries fail to import, Agent Reach raises an ImportError with instructions to install one of the supported extraction backends. The fallback logic attempts rookiepy first, then browser_cookie3, and fails gracefully with a descriptive message if neither is available.

Can I extract cookies programmatically without using the CLI?

Yes. You can import and call the extract_all function directly from agent_reach/cookie_extract.py. Pass a browser name (e.g., "chrome", "firefox") to receive a dictionary of platform-specific cookie data suitable for manual configuration or inspection.

How does Agent Reach handle cookie domains that start with a dot?

The filtering logic normalizes domain matching by checking both suffix matches (cookie.domain.endswith(d)) and exact equality after stripping the leading dot (cookie.domain == d.lstrip(".")). This ensures compatibility with both modern cookie storage formats and legacy domain specifications that prefix domains with dots.

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