# How Agent-Reach Extracts Browser Cookies with `--from-browser`: A Technical Deep Dive

> Discover how Agent-Reach uses --from-browser to extract browser cookies from Chrome Firefox Edge Brave Opera. Learn about the pipeline filtering and injection process.

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

---

**Agent-Reach's `--from-browser` flag triggers a multi-stage pipeline that reads authentication cookies directly from Chrome, Firefox, Edge, Brave, or Opera using `rookiepy` or `browser-cookie3`, filters them by platform-specific domain patterns, and automatically injects them into the configuration file with secure 0600 permissions.**

Agent-Reach simplifies social media automation by allowing users to import existing browser sessions via the `--from-browser` CLI option. This feature eliminates manual cookie copying by extracting tokens directly from the browser's local storage and mapping them to the correct configuration keys. Understanding this mechanism requires examining the interaction between the CLI parser, the cookie extraction module, and the platform-specific filtering logic implemented in the source code.

## Architecture of the `--from-browser` Pipeline

### CLI Argument Parsing

The command-line interface defines the `--from-browser` flag within the configure subcommand. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the argument parser accepts this flag between lines 125-130, specifying the target browser name (e.g., `chrome`, `firefox`). When the `configure` action is invoked, the method checks for `args.from_browser` and initiates the extraction sequence by calling the cookie extraction module.

### Extraction Entry Point

The `configure_from_browser(browser, config)` function in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) (lines 32-38) serves as the primary orchestrator. This function accepts a browser identifier and a `Config` object, then coordinates the entire extraction workflow. It first invokes `extract_all(browser)` to retrieve raw cookie data, then processes the results to populate the configuration object, and finally returns a status list detailing success or failure for each supported platform.

## How Cookies Are Extracted and Processed

### Reading Browser Cookie Stores

The extraction layer attempts to use **`rookiepy`** first—a Rust-based library that provides reliable access to browser cookie databases—and falls back to **`browser-cookie3`** if the former is unavailable (lines 53-66). For the specified browser, the code executes the appropriate retrieval function (e.g., `rookiepy.chrome()` or `browser_cookie3.firefox()`), which yields cookie objects exposing `.name`, `.value`, and `.domain` attributes.

### Platform-Specific Filtering

The extraction logic relies on 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) (lines 13-39). This structure maps platform identifiers to their domain patterns and required cookie names for Twitter/X, XiaoHongShu (XHS), Bilibili, and Xueqiu.

The filtering process iterates over every retrieved cookie and:
- Matches the cookie's domain against platform-specific patterns (e.g., `.twitter.com`, `.xiaohongshu.com`)
- For **Twitter** and **Bilibili**, extracts specific named cookies (`auth_token`, `ct0`, `SESSDATA`)
- For **XiaoHongShu** and **Xueqiu**, constructs a combined `cookie_string` in the format `name1=val1; name2=val2` from all cookies matching the domain

The results are assembled into a dictionary keyed by platform identifiers (`twitter`, `xhs`, `bilibili`, `xueqiu`) and returned to the caller (lines 44-52 and 114-145).

### Configuration Integration and Legacy Sync

Once extracted, the credentials are applied to the Agent-Reach configuration through specific setter methods. For Twitter credentials, the system stores `twitter_auth_token` and `twitter_ct0` via `config.set()` calls, then **syncs** these tokens to legacy tools (`xfetch` and `bird`) by writing a JSON file and a private `.env` file in the user's configuration directory (lines 76-98).

For other platforms, the values are stored directly in the Agent-Reach YAML configuration:
- XiaoHongShu: `xhs_cookie`
- Bilibili: `bilibili_sessdata`
- Xueqiu: `xueqiu_cookie` (lines 66-88 and 73-81)

### Security and File Permissions

All credential file writes utilize the **`_open_owner_only()`** helper to ensure newly created files receive `0600` permissions (owner read/write only), preventing accidental exposure of sensitive tokens to other system users (lines 49-70).

## Practical Implementation Examples

### Command-Line Usage

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

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

```

Use Firefox instead:

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

```

### Programmatic Access

 you can invoke the same logic programmatically without the CLI:

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

# Load existing configuration

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

# Extract from Chrome and apply

status = configure_from_browser("chrome", cfg)

# Review results

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

```

## Key Files and Implementation Details

| File | Role | Source Reference |
|------|------|------------------|
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Parses `--from-browser` argument and dispatches to extraction logic | [Lines 125-130](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L125-L130) |
| [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) | Core extraction logic, platform specifications, and configuration integration | [Lines 32-38](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L32-L38), [Lines 13-39](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L13-L39) |
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) | Handles YAML configuration persistence and value retrieval | Implicitly called by `configure_from_browser` |
| [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) | Provides `make_private_dir` and permission utilities used by `_open_owner_only` | Referenced in extraction logic |

## Summary

- **Agent-Reach** provides seamless cookie extraction via the `--from-browser` CLI flag, supporting Chrome, Firefox, Edge, Brave, and Opera.
- The extraction pipeline uses `rookiepy` with a `browser-cookie3` fallback to read browser databases directly from the filesystem.
- Platform-specific filtering in `PLATFORM_SPECS` ensures only relevant authentication tokens are extracted for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
- Extracted credentials are written to the Agent-Reach configuration file with strict `0600` permissions, and Twitter tokens are additionally synced to legacy helper tools.
- The entire process is encapsulated in the `configure_from_browser()` function, which returns detailed status information for each platform.

## Frequently Asked Questions

### Which browsers are supported by `--from-browser`?

Agent-Reach supports **Chrome**, **Firefox**, **Edge**, **Brave**, and **Opera**. The underlying `rookiepy` and `browser-cookie3` libraries handle the specific database locations and formats for each browser across Windows, macOS, and Linux operating systems.

### What happens if `rookiepy` is not installed?

The extraction logic automatically falls back to **`browser-cookie3`** if `rookiepy` is unavailable in the Python environment. This fallback occurs in the `extract_all()` function within [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), ensuring the feature remains functional regardless of which library is present.

### How does Agent-Reach secure extracted cookies?

All credential files are created using the **`_open_owner_only()`** helper, which sets file permissions to `0600` (readable and writable only by the owner). This prevents other users on the system from accessing sensitive authentication tokens stored in the configuration directory.

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

Yes. The `configure_from_browser(browser, config)` function in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) is designed for programmatic use. You can instantiate a `Config` object, pass it along with a browser name (e.g., `"chrome"`), and receive a list of tuples containing `(platform, success, message)` for each configured service.