How Cookie Auto-Extraction from Chrome/Firefox Works in Agent Reach

Agent Reach automatically extracts authentication cookies from Chrome, Firefox, Edge, Brave, and Opera using a dual-backend extractor that reads encrypted SQLite stores and maps them to platform-specific credentials.

Agent Reach includes a self-contained cookie extraction system that eliminates manual copy-pasting of authentication tokens from your browser. Located in the agent_reach/cookie_extract.py module, this feature supports automatic cookie auto-extraction from Chrome/Firefox and other Chromium-based browsers by directly reading their encrypted SQLite databases. The extractor integrates seamlessly with the configuration system to populate credentials for platforms like Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.

The Extraction Architecture

Dual Backend Strategy

The extractor implements a fault-tolerant backend selection mechanism. It first attempts to import rookiepy, a Rust-based wrapper that provides direct access to browser SQLite stores without locking issues. If rookiepy is unavailable, the system falls back to browser_cookie3, a pure-Python library with broad compatibility.

Supported Browsers

The system normalizes browser names to lowercase and validates against a supported list including chrome, firefox, edge, brave, and opera. This normalization occurs in the extract_all() function at lines 70-75 of agent_reach/cookie_extract.py.

Step-by-Step Extraction Pipeline

The cookie extraction process follows a seven-stage pipeline implemented in agent_reach/cookie_extract.py:

1. Backend Library Selection - The extract_all() function (lines 55-66) attempts to import rookiepy first, falling back to browser_cookie3 if unavailable.

2. Browser Name Normalization - Input strings are lower-cased and validated against supported browsers (lines 70-75).

3. Raw Cookie Reading - Depending on the backend, the system invokes browser-specific functions like rookiepy.chrome() or browser_cookie3.chrome() (lines 78-94 and 100-110). Both libraries automatically decrypt values using OS-specific keychains (DPAPI on Windows, Keychain on macOS, GNOME Keyring/KWallet on Linux).

4. Platform Specification Loading - The static PLATFORM_SPECS list (lines 15-41) defines domain patterns and required cookie names for each supported service.

5. Domain Filtering - The extractor iterates through cookies, retaining only those matching platform domain patterns (lines 18-28).

6. Result Shaping - Cookies are formatted either as specific name-value pairs or as concatenated header strings like name=value; ... (lines 31-47).

7. Configuration Integration - The configure_from_browser() function (lines 25-88) writes results to ~/.agent-reach/config.yaml and performs platform-specific post-processing.

Platform Specifications and Data Mapping

The PLATFORM_SPECS constant in agent_reach/cookie_extract.py (lines 15-41) defines the extraction rules for each platform. For example, Twitter/X requires specific cookies like auth_token and ct0, while XiaoHongShu extracts all cookies for its domain as a single header string.

Why Two Backends?

rookiepy offers superior performance and avoids SQLite locking issues on Windows and macOS by using Rust-based system calls. It returns plain dictionaries that the extractor wraps in normalized objects.

browser_cookie3 provides a pure-Python implementation that works out-of-the-box without additional dependencies. It serves as the fallback when rookiepy is not installed, ensuring the cookie auto-extraction feature remains functional across all environments.

Practical Usage Examples

Programmatic API Usage

from agent_reach.cookie_extract import configure_from_browser

# Create a Config instance (typically loaded by the CLI)

from agent_reach.config import Config
config = Config()

# Extract from Chrome and update configuration

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

# Results format: [(platform, success, message), ...]

print(results)

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

Command Line Interface

# Auto-extract from Chrome and update config file

agent-reach configure --from-browser chrome

# Use Firefox instead

agent-reach configure --from-browser firefox

Manual Extraction

from agent_reach.cookie_extract import extract_all

# Get raw cookie data without updating config

raw = extract_all(browser="chrome")

# Access specific platform credentials

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

Key Source Files

• agent_reach/cookie_extract.py - Core extraction logic, extract_all() and configure_from_browser() functions, and PLATFORM_SPECS definitions.
• agent_reach/config.py - Handles reading and writing to ~/.agent-reach/config.yaml.
• agent_reach/cli.py - Parses the --from-browser flag and orchestrates the extraction workflow.
• tests/test_cookie_extract_perms.py - Validates secure file permissions (0o600) and proper character escaping.

Summary

• Agent Reach uses a dual-backend approach (rookiepy preferred, browser_cookie3 fallback) to read encrypted browser cookies.
• The extract_all() function in agent_reach/cookie_extract.py handles browser detection, domain filtering, and platform-specific mapping.
• PLATFORM_SPECS defines which cookies to extract for each supported service (Twitter/X, XiaoHongShu, Bilibili, Xueqiu).
• The configure_from_browser() function bridges extraction with the configuration system, writing credentials to ~/.agent-reach/config.yaml.
• Both backends support automatic decryption via OS-native keychains across Windows, macOS, and Linux.

Frequently Asked Questions

Which browsers does Agent Reach support for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The extractor normalizes browser names and uses the appropriate backend library to read each browser's specific SQLite storage format, whether it's the Chromium-based encrypted stores or Firefox's cookies.sqlite file.

How does Agent Reach decrypt encrypted browser cookies?

The underlying libraries (rookiepy and browser_cookie3) automatically handle decryption using operating-system-specific APIs: DPAPI on Windows, Keychain on macOS, and GNOME Keyring or KWallet on Linux. This decryption occurs transparently when reading the SQLite databases, requiring no manual intervention from the user.

What happens if rookiepy is not installed?

If rookiepy is unavailable, the extractor automatically falls back to browser_cookie3, a pure-Python implementation. This fallback mechanism ensures that cookie auto-extraction from Chrome/Firefox works across all environments without requiring Rust dependencies or additional compilation steps.

Where does Agent Reach store the extracted cookies?

The configure_from_browser() function writes extracted credentials to ~/.agent-reach/config.yaml. The system also performs platform-specific post-processing, such as syncing Twitter credentials to legacy xfetch and bird configuration files, ensuring backward compatibility with existing Agent Reach workflows.

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