How Agent-Reach Auto-Extracts Cookies from Browser: A Technical Deep Dive

Agent-Reach extracts authentication cookies from Chrome, Firefox, Edge, Brave, and Opera using a dual-backend architecture that prioritizes the Rust-based rookiepy library and falls back to browser_cookie3, decrypting browser SQLite stores and mapping them to platform-specific configurations.

Agent-Reach is an open-source automation framework that eliminates manual cookie copying by reading encrypted browser storage directly. The agent-reach auto-extract cookies from browser system lives in agent_reach/cookie_extract.py and supports seamless authentication for platforms like Twitter/X, XiaoHongShu, and Bilibili without requiring users to export cookies manually.

Dual-Backend Architecture

The extraction system implements a resilient two-tier strategy to maximize compatibility across operating systems while handling encrypted browser databases.

Primary Backend: rookiepy

The extract_all() function first attempts to import rookiepy (lines 55-66), a Rust-based wrapper that reads the browser's SQLite cookie store directly. According to the Panniantong/Agent-Reach source code, this backend avoids the occasional sqlite3 locking problems on Windows and macOS, returning a list of plain dictionaries with name, value, and domain keys that the extractor wraps into standardized objects.

Fallback Backend: browser_cookie3

If rookiepy is not installed, the system falls back to the pure-Python browser_cookie3 library (lines 100-110). This library is well-maintained and works out-of-the-box in most environments, though it may encounter locking issues on some platforms when the browser is running.

Both libraries automatically decrypt values using operating-system-specific keychains: DPAPI on Windows, Keychain on macOS, and GNOME-Keyring or KWallet on Linux.

The Extraction Pipeline

Step 1: Browser Normalization

The supplied browser argument is lower-cased and validated against the supported list (chrome, firefox, edge, brave, opera) in lines 70-75 of extract_all().

Step 2: Reading Encrypted Stores

Depending on the selected backend, the system builds a dictionary of callables (rookiepy.chrome or browser_cookie3.chrome, etc.) and invokes them (lines 78-94). These libraries access Chromium-based encrypted SQLite stores (for Chrome, Edge, Brave, Opera) and Firefox's cookies.sqlite file.

Step 3: Platform-Specific Filtering

A static PLATFORM_SPECS list defined in lines 15-41 specifies, for each supported service (Twitter/X, XiaoHongShu, Bilibili, Xueqiu), the domain patterns and specific cookie names required. When cookies is None for a platform, the extractor grabs all cookies for that domain.

The extractor iterates over every cookie returned by the backend (lines 18-28), keeping those whose cookie.domain matches any platform's domain patterns. It stores either the full cookie string or selected name/value pairs (lines 31-36).

Step 4: Result Serialization

For each platform yielding data, extract_all() creates a dictionary entry under the platform's config_key (lines 38-47). If a platform requires a full header string, it assembles name=value; … pairs. The final mapping structure resembles:

{'twitter': {'auth_token': '…', 'ct0': '…'}, 
 'xhs': {'cookie_string': '…'}, 
 ...}

Configuration Integration

The higher-level helper configure_from_browser() (lines 25-88 in cookie_extract.py) bridges the extraction and configuration systems.

This function calls extract_all(), then writes discovered values into the Agent-Reach configuration file at ~/.agent-reach/config.yaml via the Config object from agent_reach/config.py. It also performs platform-specific post-processing, such as syncing Twitter credentials to legacy xfetch/bird files.

Usage Examples

Programmatic Python API

Import the configuration helper to auto-extract and save cookies:

from agent_reach.cookie_extract import configure_from_browser

# `config` is an instance of agent_reach.config.Config

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

# Returns list of (platform, success, message) tuples

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

print(results)

Command-Line Interface

End-users typically invoke the feature via the CLI defined in agent_reach/cli.py:

# Auto-extract from Chrome and update config

agent-reach configure --from-browser chrome

For Firefox users:

agent-reach configure --from-browser firefox

Manual Cookie Inspection

To check extracted data without writing to config:

from agent_reach.cookie_extract import extract_all

raw = extract_all(browser="chrome")
print(raw["twitter"]["auth_token"])   # Twitter auth token

print(raw["xhs"]["cookie_string"])   # Full XiaoHongShu header

Security and Permissions

The tests/test_cookie_extract_perms.py file verifies that credential files are written with 0o600 permissions (read/write for owner only) and that special characters in cookie values are safely quoted. This ensures that extracted session tokens remain protected on the filesystem.

Summary

• Agent-Reach auto-extracts cookies via agent_reach/cookie_extract.py using a dual-backend approach.
• The system prioritizes rookiepy (Rust-based) for speed and reliability, falling back to browser_cookie3 (pure-Python) when unavailable.
• Supported browsers include Chrome, Firefox, Edge, Brave, and Opera, with automatic OS-level decryption of SQLite stores.
• PLATFORM_SPECS defines domain patterns and specific cookie names for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• The configure_from_browser() function integrates extraction with the YAML configuration system at ~/.agent-reach/config.yaml.
• Security tests ensure credential files are created with restrictive 0o600 permissions.

Frequently Asked Questions

How does Agent-Reach decrypt Chrome's encrypted cookies?

Agent-Reach relies on underlying libraries (rookiepy or browser_cookie3) to handle decryption. These libraries use operating-system-specific APIs—DPAPI on Windows, Keychain on macOS, and GNOME-Keyring or KWallet on Linux—to decrypt the AES-256 encrypted values stored in Chromium's SQLite database without requiring manual key extraction.

What happens if rookiepy is not installed?

If the rookiepy import fails (lines 55-66), the extractor automatically falls back to browser_cookie3. This pure-Python alternative performs the same function but may occasionally encounter database locking issues on Windows or macOS when the browser is running.

Which browsers and platforms are supported?

The extractor supports Chrome, Firefox, Edge, Brave, and Opera. Platform-specific extraction is configured for Twitter/X (extracting auth_token and ct0), XiaoHongShu, Bilibili, and Xueqiu via the PLATFORM_SPECS definition in agent_reach/cookie_extract.py.

Is the extracted cookie data stored securely?

Yes. According to tests/test_cookie_extract_perms.py, Agent-Reach writes credential files with 0o600 filesystem permissions, meaning only the file owner can read or write the data. Additionally, the YAML configuration handler safely quotes special characters to prevent injection vulnerabilities.

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