# How Agent-Reach Handles Cookie Extraction from Browsers: Architecture and Implementation

> Agent-Reach extracts browser cookies from Chrome, Firefox, Edge, Brave, and Opera using a dual backend and filters them into config yaml. Learn how.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: architecture
- Published: 2026-07-01

---

**Agent-Reach extracts authentication cookies from Chrome, Firefox, Edge, Brave, and Opera using a dual-backend system that prioritizes the Rust-based `rookiepy` library, falling back to `browser_cookie3`, then filters results against platform-specific domain patterns to populate `~/.agent-reach/config.yaml`.**

The `Panniantong/Agent-Reach` repository automates the retrieval of session cookies from local browser profiles to streamline authentication for various social platforms. This article examines how the **agent-reach cookie extraction** pipeline works under the hood, from SQLite database decryption to configuration file generation.

## The Dual-Backend Architecture

The extractor in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) implements a resilient two-tier backend system to maximize compatibility across different environments.

### Primary Backend: `rookiepy`

**`rookiepy`** is a Rust-based wrapper that reads browser SQLite cookie stores directly. According to the source code (lines 55-66), this is the preferred backend because it avoids `sqlite3` locking issues on Windows and macOS, and returns cookies as a list of plain dictionaries with `name`, `value`, and `domain` keys.

### Fallback Backend: `browser_cookie3`

If `rookiepy` is not installed, the system falls back to **`browser_cookie3`**, a pure-Python library that provides equivalent functionality. Both backends automatically decrypt encrypted cookie values using OS-specific keychains: DPAPI on Windows, Keychain on macOS, and GNOME-Keyring/KWallet on Linux.

## The Extraction Pipeline in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py)

The `extract_all()` function orchestrates a six-step pipeline to transform raw browser data into structured platform credentials.

### Step 1: Backend Selection and Import

The function first attempts to import `rookiepy` (lines 55-66). If the import fails, it switches to `browser_cookie3` and logs the fallback. This ensures the tool works out-of-the-box while preferring the faster Rust implementation when available.

### Step 2: Browser Normalization

The supplied `browser` argument is lower-cased and validated against the supported list: `chrome`, `firefox`, `edge`, `brave`, and `opera` (lines 70-75). This normalization ensures consistent handling regardless of user input casing.

### Step 3: Raw Cookie Reading

Depending on the selected backend, the code builds a dictionary of callables referencing `rookiepy.chrome` (or `browser_cookie3.chrome`, etc.) and invokes the appropriate function (lines 78-94 for rookiepy, lines 100-110 for browser_cookie3). The returned objects are normalized to a wrapper class exposing `.name`, `.value`, and `.domain` attributes.

### Step 4: Platform Specification Mapping

A static `PLATFORM_SPECS` list (lines 15-41) defines extraction rules for each supported service:
- **Twitter/X**: Extracts specific cookies by name
- **XiaoHongShu**: Grabs all cookies for the domain
- **Bilibili** and **Xueqiu**: Domain-specific patterns

Each entry specifies domain patterns and required cookie names (or `None` to capture all cookies for that domain).

### Step 5: Domain Filtering and Collection

The extractor iterates over every cookie returned by the backend (lines 18-28). It keeps only those where `cookie.domain` matches any pattern defined in `PLATFORM_SPECS`. For platforms requesting specific cookies, it filters by name; otherwise, it collects all matches (lines 31-36).

### Step 6: Result Shaping

For each platform yielding data, the system creates a dictionary entry under the platform’s `config_key` (lines 38-47). If a platform requires a full header string, the code assembles it as `name=value; ...`. The final output structure resembles:

```python
{
    'twitter': {'auth_token': '...', 'ct0': '...'},
    'xhs': {'cookie_string': '...'},
    ...
}

```

## Integration with the Configuration System

The higher-level helper **`configure_from_browser()`** (lines 25-88) bridges extraction and persistence. 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

The integration also handles platform-specific post-processing. For example, when extracting Twitter credentials, it syncs the tokens to legacy `xfetch` and `bird` credential files to maintain backward compatibility.

## Practical Usage Examples

### Programmatic API

To extract cookies directly in Python:

```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'), ('XiaoHongShu', True, '12 cookies'), ...]

print(results)

```

### CLI Command

End-users typically invoke extraction via the command line:

```bash

# Extract from Chrome and auto-update config

agent-reach configure --from-browser chrome

# Extract from Firefox instead

agent-reach configure --from-browser firefox

```

The CLI parses the `--from-browser` flag in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and delegates to `configure_from_browser()`.

### Manual Inspection

For debugging or custom integrations, access raw extraction results:

```python
from agent_reach.cookie_extract import extract_all

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

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

```

## Summary

- **Agent-reach cookie extraction** supports Chrome, Firefox, Edge, Brave, and Opera through a unified interface in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py).
- The system prefers **`rookiepy`** (Rust) for performance and reliability, falling back to **`browser_cookie3`** (Python) if unavailable.
- **`PLATFORM_SPECS`** defines domain patterns and cookie names for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
- **`extract_all()`** filters raw browser cookies against platform specifications and returns structured dictionaries.
- **`configure_from_browser()`** persists extracted values to `~/.agent-reach/config.yaml` and handles platform-specific post-processing.
- Both backends automatically decrypt cookies using OS-native keychains (DPAPI, Keychain, or KWallet).

## Frequently Asked Questions

### Which browsers does agent-reach support for cookie extraction?

Agent-Reach supports Chrome, Firefox, Edge, Brave, and Opera. The extraction logic in `extract_all()` normalizes browser names to lowercase and validates them against this supported list before attempting to read the SQLite cookie stores.

### How does agent-reach decrypt encrypted browser cookies without manual input?

Both `rookiepy` and `browser_cookie3` automatically handle decryption using operating-system-specific keychains. On Windows, they use DPAPI; on macOS, the Keychain; and on Linux, GNOME-Keyring or KWallet. This allows the extraction to proceed without prompting the user for passwords or decryption keys.

### What happens if rookiepy is not installed?

If the `rookiepy` import fails, the code in `extract_all()` (lines 55-66) automatically falls back to `browser_cookie3`. While `browser_cookie3` is slightly slower and may encounter SQLite locking issues on some platforms, it provides identical functionality and works out-of-the-box in pure-Python environments.

### Where does agent-reach store the extracted cookies?

The `configure_from_browser()` function writes extracted cookies to the Agent-Reach configuration file located at `~/.agent-reach/config.yaml`. The function uses the `Config` class from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to handle file I/O and ensures credentials are written with secure permissions (typically `0o600` as verified in [`tests/test_cookie_extract_perms.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cookie_extract_perms.py)).