How Browser Cookie Extraction Works for Chrome and Firefox in Agent-Reach

Agent-Reach extracts authentication cookies from Chrome and Firefox using a dual-backend approach—preferring the Rust-based rookiepy library and falling back to browser_cookie3—then maps them to platform-specific configurations via PLATFORM_SPECS in agent_reach/cookie_extract.py.

Agent-Reach automates the retrieval of authentication cookies from local browsers to streamline API access for platforms like Twitter/X, XiaoHongShu, and Bilibili. The entire extraction logic is contained within agent_reach/cookie_extract.py, which normalizes browser selection, handles backend fallback, and filters cookies according to domain-specific requirements.

The Cookie Extraction Pipeline

The extract_all() function orchestrates a seven-step process to harvest browser cookies and transform them into usable authentication headers. According to the Panniantong/Agent-Reach source code, this pipeline isolates low-level browser reading from high-level configuration logic.

Browser Selection and Normalization

The process begins when the caller passes a browser identifier—chrome, firefox, edge, brave, or opera—to the extraction function. Lines 70-76 in cookie_extract.py normalize this input and validate it against the supported list, ensuring consistent handling regardless of case or formatting variations.

Backend Selection Strategy

Agent-Reach implements a resilient dual-backend strategy for reading encrypted browser stores:

• rookiepy: A Rust-based library preferred for its stability and performance. The code attempts to import this first at lines 55-64.
• browser_cookie3: A pure-Python fallback used when rookiepy is unavailable.

This fallback mechanism ensures cross-platform compatibility without requiring external Rust dependencies in restricted environments.

Raw Cookie Retrieval

Once the backend is selected, the code invokes browser-specific helpers—such as rookiepy.chrome() or browser_cookie3.firefox()—to return an iterable of cookie objects. Each object exposes at minimum the name, value, and domain attributes, as referenced in lines 78-108.

Platform-Specific Cookie Mapping with PLATFORM_SPECS

The PLATFORM_SPECS dictionary (lines 15-41) defines the extraction rules for each supported service, including domain patterns and required cookie keys.

Domain Pattern Matching

The code iterates through every cookie in the jar and checks whether its domain ends with any of the platform's specified domain patterns (lines 22-28). This substring matching allows the system to capture cookies from both root domains and subdomains without explicit enumeration.

Selective Cookie Extraction

For platforms requiring specific authentication tokens, the code filters cookies by name. If a platform defines a list of required cookie names in its spec, only those names are collected; otherwise, all domain-matched cookies are joined into a single header-style string (lines 33-44). The results are stored under each platform's config_key, such as "twitter" or "xhs".

Legacy Credential Synchronization

When Twitter/X cookies are successfully extracted, Agent-Reach triggers two legacy synchronization helpers to maintain compatibility with external tools. Lines 199-205 implement:

• _sync_xfetch_session: Writes tokens to ~/.config/xfetch/session.json
• _sync_bird_env: Creates a sourceable environment file at ~/.config/bird/credentials.env containing AUTH_TOKEN and CT0 variables for the bird CLI

Integrating Extraction into Configuration

The configure_from_browser() function serves as the primary entry point for CLI and programmatic usage. It calls extract_all(), writes extracted values into the central Config object via config.set() (e.g., config.set("twitter_auth_token", ...)), and returns a status tally indicating which platforms succeeded (lines 25-31, 44-61).

Practical Implementation Examples

Command-Line Configuration

Use the built-in CLI to auto-configure all supported platforms from Chrome:

python -m agent_reach.cli configure --from-browser chrome

This triggers configure_from_browser("chrome", config) and updates the Agent-Reach configuration file automatically.

Programmatic Cookie Extraction

Extract cookies directly in Python for custom workflows:

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

# Extract raw cookies from Firefox

cookies = extract_all("firefox")
print(cookies)

# Output: {'twitter': {'auth_token': '...', 'ct0': '...'}, 'xhs': {'cookie_string': '...'}}

# Apply to configuration instance

cfg = Config()
status = configure_from_browser("firefox", cfg)
print(status)

# Output: [('Twitter/X', True, 'auth_token + ct0'), ('XiaoHongShu', True, '12 cookies')]

# Access specific tokens

auth_token = cfg.get("twitter_auth_token")

Extending PLATFORM_SPECS for New Platforms

Add custom platform support without modifying core logic:

# In agent_reach/cookie_extract.py

PLATFORM_SPECS.append({
    "name": "MySite",
    "domains": [".mysite.com"],
    "cookies": ["mysess", "mycsrf"],
    "config_key": "mysite",
})

The next extract_all() call automatically includes the new specification.

Summary

• Agent-Reach extracts Chrome and Firefox cookies via agent_reach/cookie_extract.py using either rookiepy or browser_cookie3 backends.
• The PLATFORM_SPECS dictionary defines domain patterns and required cookies for each supported platform, enabling automatic filtering of relevant authentication tokens.
• Legacy synchronization maintains compatibility with external tools like xfetch and bird by writing credentials to standard filesystem locations.
• The configure_from_browser() function bridges extraction and configuration, returning detailed status tuples for CLI feedback.

Frequently Asked Questions

What browsers does Agent-Reach support for cookie extraction?

Agent-Reach supports Chrome, Firefox, Edge, Brave, and Opera. The extract_all() function normalizes browser names and validates them against this supported list (lines 70-76).

Why does Agent-Reach use two different libraries for cookie extraction?

The system prefers rookiepy (Rust-based) for its stability and performance characteristics, but falls back to browser_cookie3 (pure-Python) when the Rust library is unavailable. This dual-backend approach ensures compatibility across diverse deployment environments without forcing external dependencies.

How does Agent-Reach determine which cookies belong to which platform?

The code uses the PLATFORM_SPECS configuration to match cookie domains against platform-specific patterns (lines 22-28). If a platform specifies required cookie names, only those are extracted; otherwise, all matching domain cookies are concatenated into a header string (lines 33-44).

Where are extracted Twitter/X cookies stored for legacy tool compatibility?

When Twitter cookies are detected, Agent-Reach writes them to two locations: ~/.config/xfetch/session.json via _sync_xfetch_session() and ~/.config/bird/credentials.env via _sync_bird_env(), allowing the bird CLI to source AUTH_TOKEN and CT0 variables directly.

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