# How Agent-Reach Extracts Browser Cookies Using the --from-browser Flag

> Learn how Agent-Reach uses the --from-browser flag to securely extract browser cookies via rookiepy or browser-cookie3, filtering and injecting them into its YAML config for enhanced authentication.

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

---

**Agent-Reach's `--from-browser` flag triggers a secure pipeline that reads authentication cookies directly from your browser's SQLite or encrypted stores using `rookiepy` or `browser-cookie3`, filters them by platform-specific domain patterns, and injects them into the tool's YAML configuration with owner-only file permissions.**

Agent-Reach is an open-source automation framework that eliminates manual cookie copy-pasting by importing authentication tokens directly from your browser. When you run the `configure` command with the `--from-browser` flag, the tool executes a multi-stage extraction process that maps browser cookies to platform-specific configuration keys for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.

## CLI Argument Parsing and Dispatch

The command-line interface defines the `--from-browser` argument within the `configure` subcommand group in [[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L125-L130). When this flag is present, the `Cli.configure()` method delegates execution to the cookie extraction module.

```python

# From agent_reach/cli.py

if args.from_browser:
    # Delegates to cookie_extract.configure_from_browser()

    self.configure_from_browser(args)

```

This dispatch triggers the core extraction routine [`configure_from_browser(browser, config)`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L32-L38) located in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), which orchestrates the entire import process.

## The Cookie Extraction Architecture

### Platform Specification Mapping

Before reading any browser data, Agent-Reach consults the `PLATFORM_SPECS` dictionary defined at the top of [[`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L13-L39). This structure maps supported platforms to their domain patterns and required cookie names:

- **Twitter/X**: Requires `auth_token` and `ct0` cookies from `.twitter.com`
- **XiaoHongShu**: Requires all cookies from `.xiaohongshu.com` formatted as a header string
- **Bilibili**: Requires `SESSDATA` from `.bilibili.com`
- **Xueqiu**: Requires all cookies from `.xueqiu.com` formatted as a header string

### Reading Browser Storage

The [`extract_all()`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L53-L66) function handles low-level browser access. It attempts to import **rookiepy** first—a high-performance Rust-based wrapper—and falls back to **browser-cookie3** if unavailable. Depending on the specified browser (Chrome, Firefox, Edge, Brave, or Opera), it calls the corresponding library function:

```python

# Conceptual flow from extract_all()

if browser == "chrome":
    cookies = rookiepy.chrome()  # or browser_cookie3.chrome()

```

These libraries decrypt the browser's SQLite stores or use OS keyring access to return cookie objects exposing `.name`, `.value`, and `.domain` attributes.

### Filtering and Normalization

Agent-Reach iterates through the raw cookie list and applies the `PLATFORM_SPECS` filters. For platforms with explicit cookie lists like Twitter, it extracts only the named tokens. For platforms requiring full header strings like XiaoHongShu, it concatenates all matching cookies into a semicolon-delimited string (`name1=val1; name2=val2`).

The function returns a structured dictionary keyed by platform identifiers (e.g., `"twitter"`, `"xhs"`) containing the extracted values, as implemented in [lines 44-52](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L44-L52) and [lines 114-145](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L114-L145).

## Configuration Integration and Persistence

### Updating Agent-Reach Config

Back in [`configure_from_browser()`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L32-L38), the extracted dictionary is applied to the `Config` object via `config.set()` calls:

- `config.set("twitter_auth_token", value)` 
- `config.set("twitter_ct0", value)`
- `config.set("xhs_cookie", value)`
- `config.set("bilibili_sessdata", value)`
- `config.set("xueqiu_cookie", value)`

These calls update the user's `~/.agent-reach/config.yaml` file with the fresh authentication tokens.

### Legacy Tool Synchronization

Agent-Reach performs best-effort synchronization to legacy helper tools (`xfetch` and `bird`) by writing additional configuration files. This includes creating a JSON metadata file and a private `.env` file containing the tokens, ensuring compatibility with external scripts without breaking the main configuration flow (see [lines 76-98](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L76-L98)).

## Security and File Permissions

All file write operations utilize the `_open_owner_only()` helper to enforce `0600` permissions (owner read/write only) on created files. This prevents accidental exposure of sensitive authentication tokens to other system users, as implemented in [lines 49-70](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L49-L70).

## Practical Usage Examples

Extract cookies from Chrome (the default) and configure all detected platforms:

```bash
agent-reach configure --from-browser chrome

```

Use Firefox instead:

```bash
agent-reach configure --from-browser firefox

```

Programmatic usage bypassing the CLI:

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

cfg = Config()  # Loads ~/.agent-reach/config.yaml

status = configure_from_browser("chrome", cfg)

for platform, success, message in status:
    status_icon = "✅" if success else "❌"
    print(f"{platform}: {status_icon} – {message}")

```

## Summary

- The `--from-browser` flag is parsed in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and triggers `configure_from_browser()`.
- Extraction relies on `rookiepy` (preferred) or `browser-cookie3` to read encrypted browser stores.
- `PLATFORM_SPECS` defines domain patterns for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
- Cookies are filtered, shaped into platform-specific structures, and injected via `config.set()`.
- Legacy tool sync and `0600` file permissions ensure secure, backwards-compatible storage.

## Frequently Asked Questions

### Which browsers are supported by the --from-browser flag?

Agent-Reach supports Chrome, Firefox, Edge, Brave, and Opera. The underlying `rookiepy` or `browser-cookie3` libraries handle the specific decryption mechanisms for each browser's cookie storage format.

### What happens if neither rookiepy nor browser-cookie3 is installed?

If both libraries are unavailable, `extract_all()` raises an `ImportError` with instructions to install one of the dependencies. The extraction cannot proceed without one of these backends to handle browser-specific encryption.

### Is the cookie extraction process secure?

Yes. Agent-Reach only reads cookies from your local browser stores and never transmits them over the network. Written configuration files are created with `0600` permissions using `_open_owner_only()`, ensuring only your user account can read the extracted tokens.

### Why does the output show "manual login required" for some platforms?

This message appears when the browser cookie store lacks the specific tokens required by a platform's `PLATFORM_SPECS` definition. For example, if you haven't logged into XiaoHongShu in the specified browser recently, those cookies won't exist, and Agent-Reach cannot extract them automatically.