# How Agent Reach `configure --from-browser` Parses and Stores Cookies

> Learn how Agent Reach's configure --from-browser command extracts, filters, and stores browser cookies using libraries like rookiepy for seamless authentication. Get started fast!

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

---

**The `agent-reach configure --from-browser` command extracts authentication cookies from Chrome, Firefox, Edge, Brave, or Opera using the `rookiepy` or `browser_cookie3` libraries, filters them against platform-specific patterns via `extract_all()`, and persists them to `~/.agent-reach/config.yaml` using the `configure_from_browser` function in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py).**

The `configure --from-browser` option in Agent Reach automates the extraction of session cookies from popular web browsers to authenticate with social media platforms. When you run this command, the CLI delegates the heavy lifting to specialized extraction modules that read browser storage, filter cookies by domain, and persist the credentials to a YAML-based configuration file. This eliminates manual copy-pasting of cookie strings and ensures compatibility with the tool's various platform adapters.

## CLI Entry Point and Delegation

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the `--from-browser` flag triggers a call to `configure_from_browser()` from the `agent_reach.cookie_extract` module. This function accepts a browser name (e.g., `chrome`, `firefox`) and a `Config` instance, orchestrating the entire extraction and storage workflow.

The CLI supports five browsers: **Chrome**, **Firefox**, **Edge**, **Brave**, and **Opera**. You invoke the command as follows:

```bash

# Extract cookies from Chrome

agent-reach configure --from-browser chrome

# Extract cookies from Firefox

agent-reach configure --from-browser firefox

```

## The Cookie Extraction Pipeline

### Browser Library Abstraction

The `extract_all()` function in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) handles the low-level browser access. It attempts to import **rookiepy** first, falling back to **browser_cookie3** if unavailable. The function opens the browser's cookie store and reads every cookie, wrapping them in lightweight `_Cookie` objects containing `name`, `value`, and `domain` attributes.

### Platform-Specific Filtering with PLATFORM_SPECS

After extraction, the code filters cookies using a static `PLATFORM_SPECS` table that maps platforms to their required domain patterns and cookie names. The logic processes each cookie as follows:

- **Domain matching**: If a cookie's domain matches a platform's pattern, it is collected for that platform.
- **Header string platforms**: For **XiaoHongShu** and **Xueqiu**, matching cookies are concatenated into a `"name=value; ..."` string.
- **Named cookie platforms**: For **Twitter/X** and **Bilibili**, the function extracts specific cookie names (`auth_token`, `ct0`, `SESSDATA`, `bili_jct`) into a dictionary.

The result is a structured dictionary mapping platform names to their authentication data:

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

```

## Configuration Persistence and Storage

The `configure_from_browser` function receives the filtered extraction results and a `Config` instance (the central YAML-based configuration manager). It then writes platform-specific values to `~/.agent-reach/config.yaml` and generates legacy compatibility files for downstream tools.

### Twitter/X Authentication

For Twitter/X, the function saves `auth_token` to the `twitter_auth_token` key and `ct0` to `twitter_ct0`. It also writes a legacy **xfetch** session file to `~/.config/xfetch/session.json` and a **bird** environment file to `~/.config/bird/credentials.env` to maintain compatibility with external tooling.

### XiaoHongShu Header Strings

The entire concatenated cookie string for XiaoHongShu is stored under the key `xhs_cookie` in the YAML configuration.

### Bilibili Token Storage

For Bilibili, `SESSDATA` is saved to `bilibili_sessdata`, and if present, `bili_jct` is saved to `bilibili_csrf` for CSRF token validation.

### Xueqiu Validation

Xueqiu cookies are only stored if the header string contains the required `xq_a_token`. The resulting string is saved under `xueqiu_cookie`.

Each operation returns a status tuple: `("Platform Name", True, "description")` for success or `("Platform Name", False, "error message")` for failure, enabling the CLI to render a tidy status table.

## Practical Usage Examples

You can interact with the cookie extraction programmatically using the Python API:

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

cfg = Config()
results = configure_from_browser('chrome', cfg)

# Access stored credentials

print(cfg.get('twitter_auth_token'))  # AAAAAAAAAAAAAAAAAAAAAA...

print(cfg.get('xhs_cookie'))          # xsid=abc123; xhsid=def456; ...

```

The `results` list contains status tuples for each platform:

```python
[('Twitter/X', True, 'auth_token + ct0'),
 ('XiaoHongShu', True, '5 cookies'),
 ('Bilibili', True, 'SESSDATA + bili_jct'),
 ('Xueqiu', False, '找到 3 个 Cookie 但缺少 xq_a_token，...')]

```

## Summary

- **Entry point**: The `--from-browser` flag in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) delegates to `configure_from_browser()`.
- **Extraction**: Uses `rookiepy` (preferred) or `browser_cookie3` via `extract_all()` to read browser cookies into `_Cookie` objects.
- **Filtering**: `PLATFORM_SPECS` maps domains and selects specific cookies or header strings for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
- **Storage**: Saves to `~/.agent-reach/config.yaml` with keys like `twitter_auth_token`, `xhs_cookie`, and `bilibili_sessdata`.
- **Legacy support**: Generates `~/.config/xfetch/session.json` and `~/.config/bird/credentials.env` for Twitter/X tokens.

## Frequently Asked Questions

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

Agent Reach supports **Chrome**, **Firefox**, **Edge**, **Brave**, and **Opera**. The `extract_all()` function in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) attempts to use `rookiepy` first, then falls back to `browser_cookie3` to access the browser's native cookie storage.

### What happens if a required cookie is missing for a specific platform?

If required cookies are missing (for example, if Xueqiu lacks `xq_a_token`), the function returns a failure tuple with a descriptive message like `('Xueqiu', False, '找到 3 个 Cookie 但缺少 xq_a_token')`. The CLI displays this as a failed status in the output table, and no configuration is written for that platform.

### Where does Agent Reach store the extracted cookies?

Credentials are persisted to `~/.agent-reach/config.yaml` via the `Config` class. Platform-specific keys include `twitter_auth_token`, `twitter_ct0`, `xhs_cookie`, `bilibili_sessdata`, `bilibili_csrf`, and `xueqiu_cookie`.

### Why does Agent Reach create files in `~/.config/xfetch` and `~/.config/bird`?

These are legacy compatibility files generated specifically for Twitter/X authentication. When processing Twitter cookies, `configure_from_browser()` writes `~/.config/xfetch/session.json` and `~/.config/bird/credentials.env` to ensure seamless integration with the `xfetch` and `bird` downstream tools that expect credentials in those specific locations.