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

> Learn how Agent Reach automatically extracts cookies from Chrome and Firefox. Our dual-backend extractor reads encrypted SQLite stores for seamless credential mapping.

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

---

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

```python
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

```bash

# 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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py)** - Core extraction logic, `extract_all()` and `configure_from_browser()` functions, and `PLATFORM_SPECS` definitions.
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** - Handles reading and writing to `~/.agent-reach/config.yaml`.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** - Parses the `--from-browser` flag and orchestrates the extraction workflow.
- **[`tests/test_cookie_extract_perms.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.