# How Agent-Reach Extracts and Secures Browser Cookies for Twitter/X and XiaoHongShu

> Agent-Reach securely extracts browser cookies for TwitterX and XiaoHongShu, saving them to a protected YAML file. Learn how this tool safeguards your authentication tokens.

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

---

**Agent-Reach reads your local browser's cookie store, filters platform-specific authentication tokens for Twitter/X and XiaoHongShu, and writes them to a permission-locked YAML configuration file at `~/.agent-reach/config.yaml` while maintaining compatibility with legacy CLI tools.**

Agent-Reach is an open-source automation framework designed for social media platform interactions. Handling authentication credentials securely is critical when automating platforms like Twitter/X and XiaoHongShu, which is why the project implements a robust pipeline to extract and secure browser cookies directly from your local browser stores.

## Cookie Extraction Architecture

The extraction logic resides in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) and implements a two-tier fallback strategy for browser compatibility.

### Browser Library Abstraction

The `extract_all()` function attempts to use the Rust-based **rookiepy** library first, falling back to **browser-cookie3** if the import fails. Both libraries expose browser-specific functions (`chrome`, `firefox`, `edge`, `brave`, `opera`) that return iterable cookie objects containing `name`, `value`, and `domain` attributes.

### Platform Specification Mapping

The `PLATFORM_SPECS` constant (lines 13-39) defines domain patterns and required cookie names for each supported service. For Twitter/X, it targets `.x.com` and `.twitter.com` domains, extracting specific cookies named `auth_token` and `ct0`. For XiaoHongShu, it filters for `.xiaohongshu.com` domains.

## Domain Filtering and Token Extraction

Inside `extract_all()`, the code iterates through every cookie returned by the browser library. It checks whether `cookie.domain` ends with any domains declared for the target platform. When a platform's `cookies` list is defined (as with Twitter/X), only those specific names are retained; otherwise, the entire cookie set is concatenated into a header-style string (XiaoHongShu).

The function returns a dictionary keyed by the platform's `config_key` (`twitter` or `xhs`). For Twitter/X, this contains individual key-value pairs for `auth_token` and `ct0`. For XiaoHongShu, it contains a single `cookie_string` entry with the full header-formatted value.

## Secure Configuration Persistence

Once extracted, `configure_from_browser()` calls `extract_all()` and writes values to the central `Config` object using `config.set()`. Twitter tokens are stored under `twitter_auth_token` and `twitter_ct0`, while XiaoHongShu data is saved under `xhs_cookie`.

### File Permission Locking

The `Config.save()` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 52-66) creates the configuration file with mode **0o600** (owner read/write only) using `os.open` and `os.chmod`. This guarantees that extracted browser cookies are never world-readable on disk.

## Legacy Tool Compatibility

Agent-Reach synchronizes credentials with existing tools that expect specific formats.

### xfetch Session Synchronization

The `_sync_xfetch_session()` function writes a JSON file to `~/.config/xfetch/session.json` containing `authToken` and `ct0` keys, mirroring the historic xfetch format (lines 76-98).

### Bird CLI Environment Variables

The `_sync_bird_env()` helper generates a shell-sourceable `credentials.env` file under `~/.config/bird/`, exporting `AUTH_TOKEN` and `CT0` variables with safely quoted values using `shlex.quote` (lines 104-122).

## Command-Line and Programmatic Usage

Users can trigger the extraction pipeline via CLI or Python API.

### CLI Invocation

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

```

This command internally calls `cookie_extract.configure_from_browser()` and handles the full extraction-to-storage workflow.

### Python API

```python
from agent_reach.cookie_extract import extract_all

# Extract cookies from Chrome

cookies = extract_all(browser="chrome")
print(cookies)

# Output:

# {

#   "twitter": {"auth_token": "...", "ct0": "..."},

#   "xhs": {"cookie_string": "a=1; b=2; ..."},

# }

```

### Manual Configuration Fallback

When automatic extraction fails, the repository provides a manual guide at [`docs/cookie-export.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/cookie-export.md) explaining how to export cookie header strings directly from browser DevTools and paste them into the CLI.

## Summary

- **Agent-Reach** extracts browser cookies using a dual-library approach (rookiepy with browser-cookie3 fallback) to support Chrome, Firefox, Edge, Brave, and Opera.
- **Platform specifications** in `PLATFORM_SPECS` define domain patterns (`.x.com`, `.twitter.com`, `.xiaohongshu.com`) and required cookie names for targeted extraction.
- **Security** is enforced through `0o600` file permissions on `~/.agent-reach/config.yaml`, ensuring only the owner can read stored authentication tokens.
- **Legacy compatibility** maintains synchronisation with xfetch JSON sessions and Bird CLI environment variables through dedicated sync functions.
- **Multiple interfaces** support both CLI (`--from-browser`) and Python API (`extract_all()`) workflows, with manual export documentation as a fallback.

## Frequently Asked Questions

### How does Agent-Reach handle different browser types?

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-library strategy, attempting the Rust-based **rookiepy** library first for stability and falling back to **browser-cookie3** if unavailable. Both libraries provide identical interfaces for Chrome, Firefox, Edge, Brave, and Opera, yielding cookie objects with `name`, `value`, and `domain` attributes that the code filters by platform.

### What specific cookies are extracted for Twitter/X versus XiaoHongShu?

Agent-Reach extracts `auth_token` and `ct0` cookies from `.x.com` and `.twitter.com` domains for Twitter/X, storing them as individual values under `twitter_auth_token` and `twitter_ct0`. For XiaoHongShu, it extracts all cookies from `.xiaohongshu.com` and concatenates them into a single header-formatted string saved under `xhs_cookie`, as defined in the `PLATFORM_SPECS` constant.

### How does Agent-Reach secure stored cookies on disk?

The `Config.save()` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) creates the configuration file using `os.open` with mode **0o600** (owner read/write only) and applies `os.chmod` to enforce these permissions. This ensures that even if other users have filesystem access to the machine, they cannot read the extracted browser cookies from `~/.agent-reach/config.yaml`.

### Can I use the extracted cookies with other tools?

Yes, Agent-Reach maintains backward compatibility through `_sync_xfetch_session()`, which writes credentials to `~/.config/xfetch/session.json` for legacy xfetch support, and `_sync_bird_env()`, which generates `~/.config/bird/credentials.env` with shell-safe quoting via `shlex.quote`. These synchronization functions ensure seamless integration with existing CLI tools that expect specific credential formats.