Agent Reach Cookie Extraction from Browser Process: A Complete Technical Guide

Agent Reach extracts authentication cookies from Chrome, Firefox, Edge, Brave, and Opera using a dual-backend extraction strategy (preferring rookiepy with a browser_cookie3 fallback) to authenticate with Twitter/X, XiaoHongShu, Bilibili, and Xueqiu platforms.

The Agent Reach open-source tool automates the extraction of browser cookies to enable API interactions on behalf of logged-in users. The cookie extraction logic resides in agent_reach/cookie_extract.py and integrates directly with the CLI configuration system to securely store credentials for downstream automation tasks.

How Cookie Extraction Works in Agent Reach

The extraction process follows a robust pipeline that prioritizes reliability across different operating systems and browser configurations.

The Dual-Backend Strategy

Agent Reach implements a fallback architecture to maximize compatibility:

• rookiepy – A Rust-based library that reads Chromium and Firefox SQLite cookie stores directly. This backend bypasses native OS keychain prompts on macOS and offers superior speed and stability.
• browser_cookie3 – A pure-Python fallback that operates across all platforms but may require additional permissions (such as macOS keychain access dialogs).

The code attempts to import rookiepy first, falling back to browser_cookie3 only if the primary library is unavailable, as implemented in agent_reach/cookie_extract.py lines 55-63.

Supported Browsers and Validation

The system validates browser names strictly before attempting extraction. Only the following browsers are accepted:

• chrome
• firefox
• edge
• brave
• opera

If an unsupported browser is specified, the code raises a ValueError immediately (lines 70-76 in cookie_extract.py).

Platform-Specific Cookie Filtering

Each target platform declares specific domain and cookie name requirements in the PLATFORM_SPECS table (defined in lines 15-41 of cookie_extract.py). The extraction process:

1. Reads raw cookies from the browser's SQLite store
2. Filters cookies by domain suffix matching
3. Extracts specific named cookies (such as auth_token, ct0, SESSDATA, bili_jct) or builds complete header strings when cookies is None

Implementation Details in agent_reach/cookie_extract.py

The core extraction logic centers on the extract_all() function and supporting utilities that normalize cookie data across different backend libraries.

The extract_all() Function

The primary entry point extract_all(browser) (lines 44-48) orchestrates the extraction workflow:

1. Selects the appropriate backend library
2. Validates the browser parameter
3. Retrieves raw cookies from the browser process
4. Filters and formats cookies according to platform specifications
5. Returns a dictionary mapping platform keys to cookie data

Cookie Normalization and the _Cookie Class

When using rookiepy, raw cookie dictionaries are wrapped in a lightweight _Cookie class (lines 78-95) to provide consistent attribute access. This abstraction ensures that both backends expose uniform .name, .value, and .domain properties, allowing downstream code to remain backend-agnostic.

PLATFORM_SPECS Configuration

The PLATFORM_SPECS data structure defines extraction rules for each supported platform:

• Twitter/X: Requires auth_token and ct0 cookies
• XiaoHongShu: Collects full cookie strings
• Bilibili: Extracts SESSDATA and bili_jct tokens
• Xueqiu: Captures cookies when xq_a_token is present

This configuration drives the filtering logic that maps browser cookies to platform-specific configuration keys.

Integration with Configuration System

Once extracted, cookies transition from runtime memory to persistent secure storage through the configuration subsystem.

configure_from_browser() Helper

The configure_from_browser() function consumes the dictionary returned by extract_all() and persists values to agent_reach/config.py. This helper handles platform-specific storage logic:

• Twitter/X: Writes twitter_auth_token and twitter_ct0 to the main config, plus synchronizes legacy files including ~/.config/xfetch/session.json and ~/.config/bird/credentials.env
• XiaoHongShu: Stores the full cookie string as xhs_cookie
• Bilibili: Saves bilibili_sessdata and bilibili_csrf
• Xueqiu: Persists xueqiu_cookie when valid tokens are found

Secure File Permissions

Security is enforced through the _open_owner_only helper function, which creates auxiliary files with mode 0o600 (owner read/write only). This prevents race-condition exposure and ensures extracted credentials remain private to the user. The main configuration persists in ~/.agent-reach/config.yaml with secure filesystem permissions.

CLI Usage and Entry Points

The configure sub-command in agent_reach/cli.py (lines 96-104) provides the user-facing interface. When invoked with --from-browser chrome (or other supported browsers), the CLI:

1. Displays a banner explaining the extraction target
2. Delegates to configure_from_browser(browser, config)
3. Reports per-platform success or failure status

The CLI handles extraction failures gracefully, displaying helpful error messages without aborting the entire installation process.

Security Considerations

• No stdout exposure: Extracted cookies are never printed to standard output
• Restricted permissions: Configuration files and legacy sync targets use 0o600 permissions
• Private directory scope: All credentials reside in ~/.agent-reach/ or user-owned config directories

Code Examples

CLI Extraction

# Extract cookies from Chrome via command line

$ agent-reach configure --from-browser chrome
Extracting cookies from chrome…

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

Programmatic Usage

from agent_reach.cookie_extract import extract_all
import os
import subprocess
import shutil

# Extract cookies from Firefox process

cookies = extract_all('firefox')

# Use Twitter credentials with external CLI tools

twitter_bin = shutil.which('twitter')
if twitter_bin and 'twitter' in cookies:
    env = os.environ.copy()
    env['TWITTER_AUTH_TOKEN'] = cookies['twitter']['auth_token']
    env['TWITTER_CT0'] = cookies['twitter']['ct0']
    subprocess.run([twitter_bin, 'status'], env=env)

Manual Configuration Storage

from agent_reach.config import Config

# Manually persist a cookie string for XiaoHongShu

cfg = Config()
cfg.set('xhs_cookie', 'auth=abc123; sess=def456; user=789')

Summary

• Agent Reach extracts browser cookies through agent_reach/cookie_extract.py to enable authenticated API access
• Dual-backend architecture uses rookiepy (preferred) with browser_cookie3 fallback for maximum compatibility
• Supported browsers include Chrome, Firefox, Edge, Brave, and Opera, validated before extraction
• Platform specs define required cookies for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu
• Secure storage writes to ~/.agent-reach/config.yaml with 0o600 permissions and optional legacy file synchronization
• CLI integration via agent-reach configure --from-browser [name] handles extraction and reporting

Frequently Asked Questions

How does Agent Reach handle browser permission errors during cookie extraction?

When rookiepy or browser_cookie3 encounters permission denied errors (often due to the browser running or locked SQLite files), the CLI catches these exceptions and displays a helpful failure message for the specific platform. The process continues for remaining platforms rather than aborting, allowing partial configuration success.

Why does Agent Reach use two different libraries for cookie extraction?

The dual-backend approach ensures cross-platform reliability. rookiepy provides native Rust performance and bypasses macOS keychain prompts, while browser_cookie3 serves as a pure-Python fallback when Rust compilation is unavailable. This redundancy guarantees functionality across diverse development environments without requiring specific system dependencies.

What cookie names does Agent Reach extract for Twitter/X authentication?

According to the PLATFORM_SPECS configuration in agent_reach/cookie_extract.py, Agent Reach specifically extracts the auth_token and ct0 cookies from Twitter/X domains. These values are stored as twitter_auth_token and twitter_ct0 in the configuration, and additionally synchronized to legacy files like ~/.config/xfetch/session.json for compatibility with external tools.

Can Agent Reach extract cookies from browsers running in private or incognito mode?

No. The extraction libraries (rookiepy and browser_cookie3) read from the browser's persistent SQLite cookie stores on disk. Cookies from private/incognito sessions are stored in memory only and are destroyed when the browser closes, making them inaccessible to Agent Reach's extraction process.

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