# What Cookies Agent-Reach Extracts from Browsers and How It Parses Them

> Agent-Reach extracts authentication cookies from local browsers. Discover how its dual-backend pipeline parses cookie data against platform specifications. Learn the technical details.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-06-23

---

**TLDR:** Agent-Reach extracts authentication cookies from local browsers using a dual-backend extraction pipeline that filters raw cookie stores against platform-specific specifications defined in `PLATFORM_SPECS`.

Agent-Reach is an open-source automation framework that pulls authentication tokens directly from your installed web browsers to configure platform access. The extraction logic lives in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) and implements a robust parsing strategy that maps raw browser cookies to specific social media platforms. Understanding how Agent-Reach extracts and parses browser cookies helps developers integrate secure credential management into their automation workflows.

## How Agent-Reach Extracts 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) implements a dual-backend strategy to read encrypted browser stores without requiring manual cookie exports.

### Primary and Fallback Extraction Backends

Agent-Reach first attempts to import **rookiepy**, a Rust-based extractor that offers superior performance and reliability. If `rookiepy` is not installed, the system falls back to the pure-Python **browser_cookie3** library. This logic appears at lines 55-63:

```python
try:
    import rookiepy          # preferred backend

    use_rookiepy = True
except ImportError:
    import browser_cookie3   # fallback

    use_rookiepy = False

```

### Supported Browsers

Depending on the requested browser, `extract_all()` invokes the appropriate backend helper. The implementation supports **Chrome**, **Firefox**, **Edge**, **Brave**, and **Opera**. Lines 78-88 handle the `rookiepy` path, while lines 101-109 manage the `browser_cookie3` fallback:

```python

# Using rookiepy (lines 78-88)

if browser_name == "chrome":
    cookie_jar = rookiepy.chrome()
elif browser_name == "firefox":
    cookie_jar = rookiepy.firefox()

# ... additional browser mappings

# Fallback to browser_cookie3 (lines 101-109)

elif browser_name == "chrome":
    cookie_jar = browser_cookie3.chrome()

```

Both backends return an iterable of cookie objects exposing at least `name`, `value`, and `domain` attributes.

## How Agent-Reach Parses Extracted Cookies

Raw browser cookies undergo strict filtering through the **PLATFORM_SPECS** registry before being stored in the configuration.

### The PLATFORM_SPECS Registry

Defined at lines 15-41 in [`cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cookie_extract.py), `PLATFORM_SPECS` is a static list that maps platforms to their required domain patterns and authentication tokens:

```python
PLATFORM_SPECS = [
    {"name": "Twitter/X", "domains": [".x.com", ".twitter.com"],
     "cookies": ["auth_token", "ct0"], "config_key": "twitter"},
    {"name": "XiaoHongShu", "domains": [".xiaohongshu.com"],
     "cookies": None, "config_key": "xhs"},
    {"name": "Bilibili", "domains": [".bilibili.com"],
     "cookies": ["SESSDATA", "bili_jct"], "config_key": "bilibili"},
    # ... additional platforms

]

```

### Domain Matching and Filtering Logic

For each platform specification, the code iterates over the raw `cookie_jar` and retains only cookies where the `domain` attribute ends with one of the listed domain patterns. The parsing logic at lines 118-148 handles two extraction modes:

- **Named Cookie Extraction**: For platforms like Twitter/X and Bilibili, the parser collects specific cookie names (`auth_token`, `ct0`, `SESSDATA`, `bili_jct`).
- **Full Serialization**: When the `cookies` field is `None` (as with XiaoHongShu), the parser serializes all matching domain cookies into a header-formatted string (`a=1; b=2`).

### Output Format

The `extract_all()` function returns a dictionary keyed by each platform's `config_key`:

```json
{
    "twitter": {"auth_token": "...", "ct0": "..."},
    "xhs": {"cookie_string": "a=1; b=2; ..."},
    "bilibili": {"SESSDATA": "...", "bili_jct": "..."}
}

```

## Configuration Persistence and CLI Integration

The `configure_from_browser()` function (lines 225-290) bridges extraction and persistent storage.

### Writing to Agent-Reach Configuration

After extraction, `configure_from_browser()` writes the parsed cookies into the central **Config** object defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). This updates the `~/.agent_reach.yaml` file with valid authentication tokens. The function also performs convenience syncs:

- **xfetch Session Sync**: Writes Twitter tokens to the legacy xfetch session file for backward compatibility.
- **bird CLI Export**: Generates a `credentials.env` file for the optional bird command-line interface.

### Command-Line Usage

When you run `agent-reach install` or `agent-reach configure --from-browser`, the CLI (lines 71-88 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) invokes `configure_from_browser()` with a Chrome-first strategy:

```bash

# Auto-import during installation

agent-reach install --channels=twitter,xiaohongshu,bilibili

# Manual browser configuration

agent-reach configure --from-browser chrome

```

If Chrome extraction yields no cookies, the CLI automatically falls back to Firefox. Success messages display extracted tokens: "✅ Twitter/X: auth_token + ct0".

## Programmatic API Usage

You can trigger the extraction pipeline directly from Python:

```python
from agent_reach.cookie_extract import extract_all, configure_from_browser
from agent_reach.config import Config

# Initialize configuration

cfg = Config()

# Extract from Chrome

cookies = extract_all("chrome")
print(cookies)  # Platform-keyed dictionary

# Apply and persist

results = configure_from_browser("chrome", cfg)
for platform, ok, msg in results:
    status = "✅" if ok else "❌"
    print(f"{platform}: {status} {msg}")

```

## Summary

- **Agent-Reach** extracts browser cookies using a dual-backend system prioritizing `rookiepy` over `browser_cookie3` to access encrypted stores from Chrome, Firefox, Edge, Brave, and Opera.
- The **PLATFORM_SPECS** registry at lines 15-41 defines platform-specific rules that filter cookies by domain and extract either named tokens (e.g., `auth_token`, `SESSDATA`) or full cookie strings.
- The `configure_from_browser()` function persists extracted values to `~/.agent_reach.yaml` and syncs to auxiliary formats like xfetch sessions and bird CLI environment files.
- Both CLI (`agent-reach configure --from-browser`) and Python API (`extract_all()`) provide interfaces to the extraction logic implemented in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py).

## Frequently Asked Questions

### What browsers does Agent-Reach support for cookie extraction?

Agent-Reach supports **Chrome**, **Firefox**, **Edge**, **Brave**, and **Opera** through the `extract_all()` function in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py). The implementation attempts to use the Rust-based `rookiepy` library first, falling back to `browser_cookie3` if unavailable, ensuring compatibility across different system configurations.

### Which specific authentication cookies does Agent-Reach extract?

Agent-Reach targets platform-specific cookies defined in the **PLATFORM_SPECS** list. For **Twitter/X**, it extracts `auth_token` and `ct0`. For **Bilibili**, it captures `SESSDATA` and `bili_jct`. **XiaoHongShu** uses a different approach, serializing all domain-matched cookies into a single header string rather than selecting individual names.

### How does Agent-Reach handle missing or encrypted cookie stores?

If the primary `rookiepy` backend fails to import, Agent-Reach automatically falls back to the pure-Python `browser_cookie3` library. During CLI execution, if Chrome contains no valid cookies, the system automatically retries with Firefox. This resilient approach ensures extraction succeeds across diverse browser installations and permission states.

### Can I use Agent-Reach's cookie extraction in my own Python scripts?

Yes. Import `extract_all()` and `configure_from_browser()` from `agent_reach.cookie_extract` to programmatically extract cookies and update configurations. The `extract_all("browser_name")` function returns a dictionary of platform-keyed credentials, allowing you to integrate browser-based authentication into custom automation workflows without invoking the CLI.