Agent Reach Cookie Extraction Process: How It Pulls Cookies from Chrome and Firefox

Agent Reach extracts authentication cookies from Chrome and Firefox using a dual-backend system in agent_reach/cookie_extract.py, supporting Twitter/X, XiaoHongShu, Bilibili, and Xueqiu, then persists them securely to ~/.agent-reach/config.yaml with restrictive 0o600 file permissions.

The Agent Reach cookie extraction process enables seamless authentication with major social platforms by reading session data directly from local browser storage. This eliminates manual cookie copying by harvesting auth_token, SESSDATA, and other credentials from Chromium-based browsers and Firefox, then wiring them into downstream commands like doctor and channel APIs.

How the Extraction Workflow Operates

The extraction pipeline follows a strict seven-step validation and filtering process defined in agent_reach/cookie_extract.py.

User initiation triggers the flow either via the CLI (agent-reach configure --from-browser chrome) or programmatically through the extract_all(browser) function (lines 44-48). The code accepts only specific browser identifiers: chrome, firefox, edge, brave, or opera; invalid names raise a ValueError (lines 70-76).

Backend selection occurs dynamically at runtime. The system first attempts to import rookiepy, a Rust-based extractor that reads SQLite cookie stores directly. If unavailable, it falls back to browser_cookie3 (lines 55-63). This dual-backend approach ensures cross-platform compatibility regardless of which library is installed.

Raw cookie consumption varies by backend. When using rookiepy, the returned dictionaries are wrapped into a lightweight _Cookie class to provide consistent .name, .value, and .domain attributes (lines 78-95). The browser_cookie3 backend returns compatible objects natively.

Platform filtering applies the PLATFORM_SPECS table (lines 15-41), which declares required domains and cookie names for each service. The code iterates the raw cookie jar, keeping entries where the domain ends with a declared platform domain, then either extracts specific named cookies or builds a complete header string when cookies is None.

The function returns a structured dictionary mapping platform keys to credential data:

{
  "twitter": {"auth_token": "...", "ct0": "..."},
  "xhs": {"cookie_string": "a=1; b=2; ..."},
  "bilibili": {"SESSDATA": "...", "bili_jct": "..."}
}

Backend Architecture: rookiepy vs browser_cookie3

Agent Reach prioritizes rookiepy for production use because it compiles to native Rust code that bypasses OS keychain prompts on macOS and reads Chromium/Firefox SQLite files directly. This avoids the permission dialogs that often interrupt automated workflows.

browser_cookie3 serves as the pure-Python fallback. While functional across all platforms, it may require additional OS permissions (such as macOS keychain access) and runs slower than the Rust implementation. The fallback logic ensures the tool works out-of-the-box in environments where only browser_cookie3 is available.

Platform-Specific Cookie Filtering

The PLATFORM_SPECS configuration defines four supported platforms with distinct domain and cookie requirements:

• Twitter/X: Requires auth_token and ct0 from domains ending in twitter.com or x.com
• XiaoHongShu: Extracts a full cookie header string from xiaohongshu.com domains
• Bilibili: Targets SESSDATA and bili_jct from bilibili.com
• Xueqiu: Validates presence of xq_a_token before extracting the full cookie string

When processing, the code either extracts named keys individually or concatenates all matching cookies into a semicolon-delimited string suitable for HTTP headers.

Configuration Integration and Persistence

The configure_from_browser helper consumes the extraction dictionary and persists values through the Config class in agent_reach/config.py. This writes to ~/.agent-reach/config.yaml using the _open_owner_only utility, which creates files with mode 0o600 to prevent other users from reading authentication tokens (lines 51-68 in cookie_extract.py).

Platform-specific persistence behaviors include:

• 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 header string as xhs_cookie
• Bilibili: Saves bilibili_sessdata and bilibili_csrf as separate keys
• Xueqiu: Persists xueqiu_cookie only when xq_a_token is present

CLI Entry Point and Usage

The configure sub-command in agent_reach/cli.py (lines 96-104) provides the primary interface. When invoked with --from-browser, it delegates to configure_from_browser and displays per-platform status:

# Extract from Chrome

$ 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)

Supported browser flags include chrome, firefox, edge, brave, and opera. Extraction failures (such as a running browser locking the SQLite database) display helpful error messages without aborting the entire configuration process.

Programmatic Usage

Developers can invoke the extraction logic directly without the CLI:

from agent_reach.cookie_extract import extract_all
from agent_reach.config import Config

# Extract from Firefox

cookies = extract_all('firefox')

# Access Twitter credentials

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

# Persist manually

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

Security Considerations

The extraction process never prints raw cookie values to stdout. All credentials flow directly into the private configuration directory with strict permissions. The _open_owner_only helper ensures atomic file creation with owner-only read/write permissions, eliminating race-condition vulnerabilities during credential storage.

Summary

• Agent Reach extracts cookies via agent_reach/cookie_extract.py using either rookiepy (preferred) or browser_cookie3 (fallback) to read browser SQLite stores.
• The extract_all(browser) function validates browser names, filters against PLATFORM_SPECS, and returns structured credentials for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• CLI integration occurs through agent-reach configure --from-browser <name>, which delegates to configure_from_browser and writes to ~/.agent-reach/config.yaml.
• Security is enforced through 0o600 file permissions via _open_owner_only, ensuring cookies remain readable only by the file owner.
• Legacy synchronization automatically updates external tool configurations (xfetch, bird) when Twitter/X cookies are extracted.

Frequently Asked Questions

What browsers does Agent Reach support for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The code validates browser names in agent_reach/cookie_extract.py (lines 70-76) and raises a ValueError for unsupported browsers. Both Chromium-based browsers and Firefox use the same extraction pipeline but may require different backend libraries depending on platform availability.

Why does extraction fail when my browser is running?

Cookie extraction requires exclusive access to the browser's SQLite database files. If Chrome or Firefox is currently running, the database remains locked, causing rookiepy or browser_cookie3 to throw a permission error. According to the source code, the CLI handles this by displaying a helpful message without crashing the configuration process, allowing you to close the browser and retry.

How does Agent Reach secure extracted cookies?

The tool stores cookies exclusively in ~/.agent-reach/config.yaml using the _open_owner_only helper function, which creates files with 0o600 permissions (owner read/write only). This prevents other system users from accessing authentication tokens. Additionally, extracted values are never echoed to stdout during the CLI workflow, and auxiliary files like ~/.config/xfetch/session.json receive the same restrictive permissions.

Can I extract cookies programmatically without using the CLI?

Yes. Import extract_all from agent_reach.cookie_extract and call it with a browser name string such as 'chrome' or 'firefox'. The function returns a dictionary containing platform-specific credentials that you can manipulate directly or pass to the Config class for persistent storage in ~/.agent-reach/config.yaml.

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