How Agent Reach Browser Cookie Extraction Works for Chrome and Firefox

Agent Reach extracts authentication cookies from Chrome and Firefox using a dual-backend approach that reads browser SQLite stores directly and filters them against platform-specific requirements.

The Agent Reach project (Panniantong/Agent-Reach) automates the extraction of session cookies from local browsers to authenticate with platforms like Twitter/X, XiaoHongShu, Bilibili, and Xueqiu. This Agent Reach browser cookie extraction capability enables downstream commands to execute API operations on behalf of the logged-in user without manual token copying.

The Extraction Workflow

The cookie extraction logic resides in agent_reach/cookie_extract.py and follows a seven-step pipeline when invoked via the CLI (agent-reach configure --from-browser chrome) or programmatically through extract_all(browser):

1. Library Selection – The code attempts to import rookiepy first; if unavailable, it falls back to browser_cookie3.
2. Browser Validation – Only chrome, firefox, edge, brave, or opera are accepted, raising ValueError for unsupported browsers.
3. Raw Cookie Reading – The selected backend reads the browser's SQLite cookie store and returns an iterable of cookie objects.
4. Object Normalization – When using rookiepy, raw dictionaries are wrapped in a _Cookie class to provide uniform .name, .value, and .domain attributes.
5. Domain Filtering – Cookies are matched against the PLATFORM_SPECS table (lines 15-41) which declares required domains for each service.
6. Name Extraction – The code either extracts specific named cookies (e.g., auth_token, ct0, SESSDATA) or builds a complete header string when cookies is None.
7. Result Mapping – Returns a dictionary mapping platform keys to their respective cookie data structures.

Dual-Backend Architecture

The extraction engine implements a resilient fallback mechanism to ensure cross-platform compatibility:

rookiepy (Primary) – A Rust-based library that reads Chromium and Firefox SQLite cookie stores directly without requiring OS keychain access on macOS. This backend offers superior speed and stability by bypassing native security prompts.

browser_cookie3 (Fallback) – A pure-Python alternative that functions on all platforms but may trigger permission dialogs (e.g., macOS keychain access) depending on the system's security configuration.

The selection logic at lines 55-63 attempts rookiepy first, catching ImportError to transparently switch to browser_cookie3 when the former is not installed.

Platform-Specific Cookie Mapping

The PLATFORM_SPECS dictionary defines extraction rules for each supported service:

Platform	Required Domain	Cookie Names	Config Output
Twitter/X	.twitter.com, .x.com	auth_token, ct0	Individual key-value pairs
XiaoHongShu	.xiaohongshu.com	All cookies	Concatenated header string
Bilibili	.bilibili.com	SESSDATA, bili_jct	Individual key-value pairs
Xueqiu	.xueqiu.com	xq_a_token (filtered)	Header string if present

When processing XiaoHongShu, the algorithm iterates through all matching domain cookies and constructs a semicolon-delimited string (name=value; name2=value2) suitable for direct HTTP header injection.

CLI Integration and Secure Storage

The configure_from_browser function (also in cookie_extract.py) bridges extraction with persistent configuration:

1. Calls extract_all(browser) to retrieve the cookie dictionary
2. Persists values via the Config class in agent_reach/config.py to ~/.agent-reach/config.yaml
3. Synchronizes legacy formats for external tools (e.g., writes ~/.config/xfetch/session.json for Twitter/X integration)

Security Implementation – When writing auxiliary credential files, the helper _open_owner_only creates files with mode 0o600 (read/write owner only) at lines 51-68, preventing exposure through permission inheritance or race conditions. The CLI entry point in agent_reach/cli.py (lines 96-104) handles the --from-browser flag, displaying per-platform success indicators without echoing sensitive values to stdout.

Practical Usage Examples

Extract cookies from Chrome via command line:

agent-reach configure --from-browser chrome

Expected output:

Extracting cookies from chrome…

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

Programmatic extraction in Python:

from agent_reach.cookie_extract import extract_all

# Extract from Firefox

cookies = extract_all('firefox')

# Access Twitter authentication tokens

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

# Use XiaoHongShu cookie string directly

xhs_header = cookies['xhs']['cookie_string']

Manual configuration persistence:

from agent_reach.config import Config

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

Summary

• Agent Reach browser cookie extraction relies on agent_reach/cookie_extract.py to read Chrome and Firefox SQLite stores using either rookiepy (Rust) or browser_cookie3 (Python).
• The system validates browser names, normalizes cookie objects, and filters against PLATFORM_SPECS to extract platform-specific authentication tokens.
• Extracted credentials are stored in ~/.agent-reach/config.yaml with strict 0o600 file permissions, and the CLI provides a configure --from-browser interface for non-interactive setup.
• Supported platforms include Twitter/X, XiaoHongShu, Bilibili, and Xueqiu, each with distinct cookie naming and domain requirements.

Frequently Asked Questions

How does Agent Reach handle browsers that are currently running?

Agent Reach reads the SQLite cookie files directly from disk. While this generally works even when browsers are active, file locking on some operating systems may cause permission errors. The CLI catches these exceptions and displays helpful guidance without aborting the overall configuration process.

What is the difference between rookiepy and browser_cookie3 in Agent Reach?

rookiepy is a compiled Rust library preferred for its speed and ability to bypass macOS keychain prompts, while browser_cookie3 serves as a pure-Python fallback that works universally but may require additional OS permissions. The code automatically attempts rookiepy first and falls back to browser_cookie3 if the former is not installed.

Which specific cookies does Agent Reach extract for Twitter/X authentication?

For Twitter/X, Agent Reach specifically looks for auth_token and ct0 cookies from domains ending in .twitter.com or .x.com. These values are extracted individually rather than as a concatenated string, allowing them to be written to both the internal config and legacy formats like xfetch session files.

Is it safe to use Agent Reach's cookie extraction on shared computers?

The extraction itself reads only from the current user's browser profile. However, the security depends on the file permissions of ~/.agent-reach/config.yaml. Agent Reach enforces 0o600 permissions (owner read/write only) on all credential files to prevent other system users from accessing the extracted cookies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}