How Agent Reach Browser Cookie Auto-Extraction Works: Supported Browsers and Implementation

Agent Reach extracts authentication cookies directly from Chrome, Firefox, Edge, Brave, and Opera using a dual-backend system in agent_reach/cookie_extract.py, automatically decrypting browser stores and mapping them to platform-specific configuration values.

Agent Reach is an open-source automation framework that eliminates manual cookie copying by reading encrypted browser storage directly. The browser cookie auto-extraction system supports Chromium-based browsers and Firefox across Windows, macOS, and Linux, writing discovered credentials to ~/.agent-reach/config.yaml through the Config class.

Dual-Backend Architecture: rookiepy vs browser_cookie3

The extraction engine in agent_reach/cookie_extract.py implements a resilient dual-backend design that prioritizes performance while maintaining compatibility.

Primary Backend: rookiepy (Rust-Based)

rookiepy serves as the preferred extraction library. This Rust-based wrapper reads browser SQLite stores directly, avoiding the locking issues common on Windows and macOS. According to the Panniantong/Agent-Reach source code, rookiepy returns a list of plain dictionaries with name, value, and domain keys that the extractor wraps into normalized objects.

The system attempts to import rookiepy first in extract_all() at lines 55-66:

# From agent_reach/cookie_extract.py

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

Fallback Backend: browser_cookie3 (Pure Python)

When rookiepy is unavailable, the system falls back to browser_cookie3, a pure-Python library that reads encrypted cookie stores using OS-specific keychains (DPAPI on Windows, Keychain on macOS, GNOME-Keyring/KWallet on Linux). Both backends automatically decrypt values using platform-native encryption APIs.

Supported Browsers and Extraction Flow

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera through a normalized extraction pipeline.

Browser Normalization and Validation

In extract_all() at lines 70-75, the supplied browser argument is lower-cased and validated against the supported list. This ensures consistent handling whether users specify "Chrome" or "chrome".

Step-by-Step Extraction Process

The extraction follows a seven-stage pipeline:

1. Backend Selection: Attempts rookiepy import, falls back to browser_cookie3 (lines 55-66)
2. Browser Normalization: Validates against chrome, firefox, edge, brave, opera (lines 70-75)
3. Raw Cookie Reading: Invokes browser-specific functions like rookiepy.chrome() or browser_cookie3.chrome() (lines 78-94 and 100-110)
4. Domain Filtering: Matches cookies against PLATFORM_SPECS domain patterns for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu (lines 18-28)
5. Cookie Selection: Extracts specific cookie names or grabs all cookies per domain (lines 31-36)
6. Result Assembly: Builds dictionaries like {'twitter': {'auth_token': '...', 'ct0': '...'}} (lines 38-47)
7. Configuration Write: configure_from_browser() writes to ~/.agent-reach/config.yaml (lines 25-88)

Platform-Specific Cookie Mapping

The PLATFORM_SPECS static list at lines 15-41 defines domain patterns and specific cookie names required for each supported service. For Twitter/X, it extracts auth_token and ct0; for XiaoHongShu, it captures the full cookie string when cookies is set to None.

Domain matching occurs at lines 18-28, where the extractor iterates over browser cookies and keeps those matching platform-specific patterns.

Implementation Examples

Programmatic Extraction

Use configure_from_browser() to extract and configure in one call:

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

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

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

print(results)

Command-Line Interface

End-users trigger extraction via the CLI defined in agent_reach/cli.py:

# Extract from Chrome

agent-reach configure --from-browser chrome

# Extract from Firefox

agent-reach configure --from-browser firefox

Raw Cookie Access

For manual inspection without configuration updates:

from agent_reach.cookie_extract import extract_all

raw = extract_all(browser="chrome")
print(raw["twitter"]["auth_token"])
print(raw["xhs"]["cookie_string"])

Configuration Integration

The configure_from_browser() function (lines 25-88) bridges extraction and persistence. It calls extract_all(), then writes values to the YAML configuration file via the Config object. It also performs platform-specific post-processing, such as syncing Twitter credentials to legacy xfetch and bird files for backward compatibility.

Security testing in tests/test_cookie_extract_perms.py verifies that credential files are created with 0o600 permissions and that special characters are safely quoted.

Summary

• Dual-backend design: Prioritizes rookiepy (Rust) with browser_cookie3 (Python) fallback
• Five browser support: Chrome, Firefox, Edge, Brave, and Opera via normalized validation
• Platform targeting: Uses PLATFORM_SPECS to map cookies to Twitter/X, XiaoHongShu, Bilibili, and Xueqiu
• Secure storage: Writes to ~/.agent-reach/config.yaml with restricted permissions
• Multiple interfaces: Available via Python API (extract_all, configure_from_browser) and CLI (--from-browser)

Frequently Asked Questions

Which browsers does Agent Reach support for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The system normalizes browser names to lowercase and validates them against this list in extract_all() at lines 70-75. Both Chromium-based browsers and Firefox are supported across Windows, macOS, and Linux.

How does Agent Reach decrypt browser cookies?

The system relies on underlying libraries (rookiepy or browser_cookie3) to handle decryption. These libraries access the OS-specific keychain—DPAPI on Windows, Keychain on macOS, and GNOME-Keyring or KWallet on Linux—to decrypt values from the browser's SQLite cookie stores without requiring manual key input.

What happens if rookiepy is not installed?

If rookiepy is unavailable, the code in agent_reach/cookie_extract.py lines 55-66 catches the ImportError and falls back to browser_cookie3. This pure-Python alternative provides identical functionality for reading encrypted stores, ensuring the tool works out-of-the-box in environments where Rust extensions cannot be compiled.

Where does Agent Reach store extracted cookies?

Extracted credentials are written to the user's configuration file at ~/.agent-reach/config.yaml via the Config class in agent_reach/config.py. The configure_from_browser() function handles this persistence, additionally ensuring credential files are created with 0o600 permissions to restrict access to the owner only.

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