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

> Learn how Agent Reach auto-extracts browser cookies from Chrome, Firefox, Edge, Brave, and Opera. Understand its dual-backend system and automatic decryption.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-09

---

**Agent Reach extracts authentication cookies directly from Chrome, Firefox, Edge, Brave, and Opera using a dual-backend system in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python

# 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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

```bash

# 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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.