# Agent Reach Cookie Extraction Process: How It Pulls Cookies from Chrome and Firefox

> Learn how Agent Reach extracts cookies from Chrome and Firefox. This guide details the dual-backend process for secure authentication cookie retrieval.

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

---

**Agent Reach extracts authentication cookies from Chrome and Firefox using a dual-backend system in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), supporting Twitter/X, XiaoHongShu, Bilibili, and Xueqiu, then persists them securely to `~/.agent-reach/config.yaml` with restrictive 0o600 file permissions.**

The Agent Reach cookie extraction process enables seamless authentication with major social platforms by reading session data directly from local browser storage. This eliminates manual cookie copying by harvesting `auth_token`, `SESSDATA`, and other credentials from Chromium-based browsers and Firefox, then wiring them into downstream commands like `doctor` and channel APIs.

## How the Extraction Workflow Operates

The extraction pipeline follows a strict seven-step validation and filtering process defined in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py).

**User initiation** triggers the flow either via the CLI (`agent-reach configure --from-browser chrome`) or programmatically through the `extract_all(browser)` function (lines 44-48). The code accepts only specific browser identifiers: `chrome`, `firefox`, `edge`, `brave`, or `opera`; invalid names raise a `ValueError` (lines 70-76).

**Backend selection** occurs dynamically at runtime. The system first attempts to import **rookiepy**, a Rust-based extractor that reads SQLite cookie stores directly. If unavailable, it falls back to **browser_cookie3** (lines 55-63). This dual-backend approach ensures cross-platform compatibility regardless of which library is installed.

**Raw cookie consumption** varies by backend. When using `rookiepy`, the returned dictionaries are wrapped into a lightweight `_Cookie` class to provide consistent `.name`, `.value`, and `.domain` attributes (lines 78-95). The `browser_cookie3` backend returns compatible objects natively.

**Platform filtering** applies the `PLATFORM_SPECS` table (lines 15-41), which declares required domains and cookie names for each service. The code iterates the raw cookie jar, keeping entries where the domain ends with a declared platform domain, then either extracts specific named cookies or builds a complete header string when `cookies` is `None`.

The function returns a structured dictionary mapping platform keys to credential data:

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

```

## Backend Architecture: rookiepy vs browser_cookie3

Agent Reach prioritizes **rookiepy** for production use because it compiles to native Rust code that bypasses OS keychain prompts on macOS and reads Chromium/Firefox SQLite files directly. This avoids the permission dialogs that often interrupt automated workflows.

**browser_cookie3** serves as the pure-Python fallback. While functional across all platforms, it may require additional OS permissions (such as macOS keychain access) and runs slower than the Rust implementation. The fallback logic ensures the tool works out-of-the-box in environments where only `browser_cookie3` is available.

## Platform-Specific Cookie Filtering

The `PLATFORM_SPECS` configuration defines four supported platforms with distinct domain and cookie requirements:

- **Twitter/X**: Requires `auth_token` and `ct0` from domains ending in `twitter.com` or `x.com`
- **XiaoHongShu**: Extracts a full cookie header string from `xiaohongshu.com` domains
- **Bilibili**: Targets `SESSDATA` and `bili_jct` from `bilibili.com`
- **Xueqiu**: Validates presence of `xq_a_token` before extracting the full cookie string

When processing, the code either extracts named keys individually or concatenates all matching cookies into a semicolon-delimited string suitable for HTTP headers.

## Configuration Integration and Persistence

The `configure_from_browser` helper consumes the extraction dictionary and persists values through the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). This writes to `~/.agent-reach/config.yaml` using the `_open_owner_only` utility, which creates files with mode **0o600** to prevent other users from reading authentication tokens (lines 51-68 in [`cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cookie_extract.py)).

Platform-specific persistence behaviors include:

- **Twitter/X**: Writes `twitter_auth_token` and `twitter_ct0` to the main config, plus synchronizes legacy files including `~/.config/xfetch/session.json` and `~/.config/bird/credentials.env`
- **XiaoHongShu**: Stores the full header string as `xhs_cookie`
- **Bilibili**: Saves `bilibili_sessdata` and `bilibili_csrf` as separate keys
- **Xueqiu**: Persists `xueqiu_cookie` only when `xq_a_token` is present

## CLI Entry Point and Usage

The `configure` sub-command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 96-104) provides the primary interface. When invoked with `--from-browser`, it delegates to `configure_from_browser` and displays per-platform status:

```bash

# Extract from Chrome

$ agent-reach configure --from-browser chrome
Extracting cookies from chrome…

✅ Twitter/X: auth_token + ct0
✅ XiaoHongShu: 12 cookies
✅ Bilibili: SESSDATA + bili_jct
✅ Xueqiu: 8 cookies (含 xq_a_token)

```

Supported browser flags include `chrome`, `firefox`, `edge`, `brave`, and `opera`. Extraction failures (such as a running browser locking the SQLite database) display helpful error messages without aborting the entire configuration process.

## Programmatic Usage

Developers can invoke the extraction logic directly without the CLI:

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

# Extract from Firefox

cookies = extract_all('firefox')

# Access Twitter credentials

auth_token = cookies['twitter']['auth_token']
ct0 = cookies['twitter']['ct0']

# Persist manually

cfg = Config()
cfg.set('xhs_cookie', 'auth=abc; sess=def')

```

## Security Considerations

The extraction process never prints raw cookie values to stdout. All credentials flow directly into the private configuration directory with strict permissions. The `_open_owner_only` helper ensures atomic file creation with owner-only read/write permissions, eliminating race-condition vulnerabilities during credential storage.

## Summary

- **Agent Reach** extracts cookies via [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) using either `rookiepy` (preferred) or `browser_cookie3` (fallback) to read browser SQLite stores.
- The **`extract_all(browser)`** function validates browser names, filters against `PLATFORM_SPECS`, and returns structured credentials for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
- **CLI integration** occurs through `agent-reach configure --from-browser <name>`, which delegates to `configure_from_browser` and writes to `~/.agent-reach/config.yaml`.
- **Security** is enforced through 0o600 file permissions via `_open_owner_only`, ensuring cookies remain readable only by the file owner.
- **Legacy synchronization** automatically updates external tool configurations (xfetch, bird) when Twitter/X cookies are extracted.

## Frequently Asked Questions

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

Agent Reach supports **Chrome**, **Firefox**, **Edge**, **Brave**, and **Opera**. The code validates browser names in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) (lines 70-76) and raises a `ValueError` for unsupported browsers. Both Chromium-based browsers and Firefox use the same extraction pipeline but may require different backend libraries depending on platform availability.

### Why does extraction fail when my browser is running?

Cookie extraction requires exclusive access to the browser's SQLite database files. If Chrome or Firefox is currently running, the database remains locked, causing `rookiepy` or `browser_cookie3` to throw a permission error. According to the source code, the CLI handles this by displaying a helpful message without crashing the configuration process, allowing you to close the browser and retry.

### How does Agent Reach secure extracted cookies?

The tool stores cookies exclusively in `~/.agent-reach/config.yaml` using the `_open_owner_only` helper function, which creates files with **0o600** permissions (owner read/write only). This prevents other system users from accessing authentication tokens. Additionally, extracted values are never echoed to stdout during the CLI workflow, and auxiliary files like `~/.config/xfetch/session.json` receive the same restrictive permissions.

### Can I extract cookies programmatically without using the CLI?

Yes. Import `extract_all` from `agent_reach.cookie_extract` and call it with a browser name string such as `'chrome'` or `'firefox'`. The function returns a dictionary containing platform-specific credentials that you can manipulate directly or pass to the `Config` class for persistent storage in `~/.agent-reach/config.yaml`.