How Auto Cookie Extraction from Browsers Works in Agent Reach: A Complete Technical Guide

Agent Reach implements a dual-backend cookie extractor in agent_reach/cookie_extract.py that reads encrypted browser SQLite stores via rookiepy or browser_cookie3, filters cookies against platform-specific domain patterns defined in PLATFORM_SPECS, and persists them to ~/.agent-reach/config.yaml through the configure_from_browser() helper.

Agent Reach, an open-source automation framework hosted at Panniantong/Agent-Reach, eliminates manual cookie copying by implementing sophisticated auto cookie extraction from browsers. This feature automatically harvests authentication tokens from Chrome, Firefox, Edge, Brave, and Opera, then maps them to the specific platform configurations required for social media automation. Understanding how auto cookie extraction from browsers works in Agent Reach reveals a robust architecture that balances performance, security, and cross-platform compatibility.

The Cookie Extraction Architecture

The extraction logic resides in agent_reach/cookie_extract.py, which orchestrates a multi-stage pipeline to safely retrieve encrypted browser cookies.

Dual Backend Strategy: rookiepy vs browser_cookie3

The extract_all() function implements a resilient fallback mechanism. Beginning at lines 55-66, it first attempts to import rookiepy, a Rust-based wrapper that directly accesses browser SQLite stores and avoids locking issues common on Windows and macOS. If rookiepy is unavailable, the code falls back to the pure-Python browser_cookie3 library.

Both backends handle the decryption automatically using OS-specific keychains—DPAPI on Windows, Keychain on macOS, and GNOME-Keyring or KWallet on Linux. While rookiepy returns plain dictionaries, browser_cookie3 returns objects that the extractor normalizes to a consistent interface exposing .name, .value, and .domain attributes.

Browser Validation and Normalization

At lines 70-75, the extract_all() function validates the user-supplied browser name by converting it to lowercase and checking against the supported list: chrome, firefox, edge, brave, and opera. This normalization ensures consistent behavior regardless of input casing.

Platform-Specific Cookie Filtering

Raw browser cookies require filtering to isolate only the authentication tokens relevant to Agent Reach's supported platforms.

PLATFORM_SPECS Configuration

Lines 15-41 define the PLATFORM_SPECS static list, which maps services like Twitter/X, XiaoHongShu, Bilibili, and Xueqiu to their specific domain patterns and required cookie names. Each specification dictates whether to extract specific named cookies (such as auth_token and ct0 for Twitter) or capture all cookies for a given domain.

Domain Matching and Collection Logic

Between lines 18-28 and 31-36, the extractor iterates through all cookies returned by the selected backend. It performs domain pattern matching against the PLATFORM_SPECS entries, collecting either specific name-value pairs or complete cookie strings when the specification requires a full header. The logic handles the assembly of cookie strings in the format name=value; ... for platforms requiring complete header data.

Configuration Integration and Persistence

The extraction pipeline concludes with persistent storage and platform-specific post-processing.

The configure_from_browser() Helper

The configure_from_browser() function, spanning lines 25-88 in the same file, serves as the high-level interface. It invokes extract_all(), then writes discovered credentials into the user's configuration file at ~/.agent-reach/config.yaml via the Config class from agent_reach/config.py.

This helper also performs platform-specific synchronization tasks, such as writing Twitter credentials to legacy xfetch or bird files for backward compatibility. The function returns a list of tuples indicating extraction success per platform: (platform_name, success_boolean, message_string).

Practical Usage Examples

Command-Line Interface

Users can trigger extraction directly from the terminal:

# Extract from Chrome and auto-update config

agent-reach configure --from-browser chrome

# Extract from Firefox

agent-reach configure --from-browser firefox

The CLI implementation in agent_reach/cli.py parses the --from-browser flag, instantiates a Config object, and delegates to configure_from_browser().

Programmatic Python API

For custom automation scripts, import the extraction utilities directly:

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

# Initialize configuration

config = Config()

# Extract from Chrome and update configuration

results = configure_from_browser(browser="chrome", config=config)

# Results format: [('Twitter/X', True, 'auth_token + ct0'), ...]

for platform, success, message in results:
    print(f"{platform}: {'Success' if success else 'Failed'} - {message}")

Raw Cookie Inspection

To access extracted data without updating configuration:

from agent_reach.cookie_extract import extract_all

# Returns dict mapping platform keys to cookie data

raw_cookies = extract_all(browser="chrome")

# Access specific tokens

twitter_token = raw_cookies["twitter"]["auth_token"]
xhs_header = raw_cookies["xhs"]["cookie_string"]

Summary

• Agent Reach implements browser cookie extraction in agent_reach/cookie_extract.py using a dual-backend architecture.
• The system prioritizes the Rust-based rookiepy library, falling back to browser_cookie3 for broader compatibility.
• Domain filtering via PLATFORM_SPECS (lines 15-41) ensures only relevant authentication cookies are extracted for specific platforms.
• The configure_from_browser() function handles the complete workflow: extraction, validation, and persistence to ~/.agent-reach/config.yaml.
• Both CLI and programmatic APIs support Chrome, Firefox, Edge, Brave, and Opera through a unified interface.

Frequently Asked Questions

Which browsers does Agent Reach support for automatic cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The extract_all() function validates these browsers at lines 70-75, and both rookiepy and browser_cookie3 backends can read the encrypted SQLite stores used by Chromium-based browsers and Firefox's cookies.sqlite file.

How does Agent Reach decrypt browser cookies without asking for passwords?

The extraction relies on rookiepy or browser_cookie3 to handle decryption through native OS keychain APIs. These libraries access the same encryption keys the browser uses—DPAPI on Windows, Keychain on macOS, and GNOME-Keyring or KWallet on Linux—allowing seamless decryption without manual password entry.

What happens if the rookiepy library is not installed?

If rookiepy is unavailable, the code in extract_all() (lines 55-66) automatically falls back to browser_cookie3. This pure-Python alternative provides identical functionality but may encounter occasional SQLite locking issues on certain platforms, whereas the Rust-based rookiepy offers superior performance and reliability.

Where does Agent Reach store the extracted cookies?

The configure_from_browser() function writes extracted credentials to ~/.agent-reach/config.yaml using the Config class from agent_reach/config.py. The system also performs platform-specific post-processing, such as syncing Twitter tokens to legacy credential files, ensuring compatibility with various Agent Reach components.

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