How Does Agent Reach Extract Cookies from Browsers: A Complete Technical Guide

Agent Reach extracts authentication cookies from local Chrome, Firefox, Edge, Brave, and Opera browsers using either the Rust-based rookiepy library or the pure-Python browser_cookie3 fallback, then filters them against a static PLATFORM_SPECS registry to match specific domains and cookie names required for each social media platform.

The Panniantong/Agent-Reach repository automates social media authentication by reading browser cookies directly from your local cookie stores. This eliminates manual token copy-pasting by programmatically accessing the encrypted SQLite databases that modern browsers use to persist session data.

Two-Stage Backend Architecture

Agent Reach implements a resilient dual-backend system in agent_reach/cookie_extract.py to maximize compatibility across different environments.

Primary Backend: rookiepy

The extraction logic first attempts to import rookiepy, a Rust-based extractor that offers superior performance and reliability when reading browser-specific encryption. As implemented in lines 55-63 of cookie_extract.py:

try:
    import rookiepy          # preferred backend

    use_rookiepy = True
except ImportError:
    import browser_cookie3   # fallback

When rookiepy is available, Agent Reach invokes browser-specific helpers like rookiepy.chrome() or rookiepy.firefox() to return raw cookie iterables.

Fallback Backend: browser_cookie3

If rookiepy is not installed, the code automatically falls back to browser_cookie3, a pure-Python implementation that supports the same major browsers. This fallback ensures the tool functions even in environments where Rust compilations are unavailable. The fallback logic appears in lines 101-109 of the same file.

Platform-Specific Cookie Filtering

Raw browser cookies are not immediately usable. Agent Reach must isolate only the authentication tokens required for specific platforms like Twitter/X, XiaoHongShu, and Bilibili.

The PLATFORM_SPECS Registry

Lines 15-41 of cookie_extract.py define a static list called PLATFORM_SPECS that declaratively specifies which domains and cookie names each platform requires:

PLATFORM_SPECS = [
    {"name": "Twitter/X", "domains": [".x.com", ".twitter.com"],
     "cookies": ["auth_token", "ct0"], "config_key": "twitter"},
    {"name": "XiaoHongShu", "domains": [".xiaohongshu.com"],
     "cookies": None, "config_key": "xhs"},
    # … other platforms …

]

Domain Matching and Cookie Extraction

The extract_all() function (lines 78-88 and 118-148) iterates through the browser's cookie jar and applies two filtering strategies:

1. Named Cookie Collection – For platforms like Twitter/X, it keeps only cookies whose names match the required list (auth_token, ct0, SESSDATA, etc.).
2. Header Serialization – When cookies is None (as with XiaoHongShu), it serializes the entire matching domain subset into a single cookie_string formatted as key=value; key2=value2.

The function returns a dictionary keyed by config_key:

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

Configuration Integration and Persistence

Extracted tokens must be written to Agent Reach's central configuration system to be used by downstream channel modules.

The configure_from_browser Function

Lines 225-290 of cookie_extract.py implement configure_from_browser(), which orchestrates the full extraction pipeline:

1. Calls extract_all() with the specified browser name (chrome, firefox, edge, brave, or opera).
2. Validates that extracted cookies contain all required fields for each platform.
3. Writes validated tokens into the central Config object (defined in agent_reach/config.py).
4. Performs ancillary syncs, including updating legacy xfetch session files and generating a credentials.env file for the optional bird CLI.

The configuration is ultimately persisted to ~/.agent_reach.yaml, making tokens available for subsequent API calls without repeated browser access.

CLI Usage and Automation

Agent Reach exposes this functionality through its command-line interface defined in agent_reach/cli.py (lines 71-88).

Automatic Extraction During Installation

When running the setup command, the CLI attempts automatic cookie import:

agent-reach install --channels=twitter,xiaohongshu,bilibili

This command triggers configure_from_browser() for Chrome first, then falls back to Firefox if no cookies are found. Users see friendly status messages indicating success or failure per platform.

Manual Browser Import

For existing installations, force a specific browser import using:

agent-reach configure --from-browser chrome

Practical Code Examples

Programmatic Usage

Import the extraction utilities directly to integrate cookie harvesting into custom scripts:

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

# Initialize or load existing configuration

cfg = Config()

# Extract cookies from Chrome

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

# Apply to configuration with detailed feedback

results = configure_from_browser("chrome", cfg)
for platform, ok, msg in results:
    print(f"{platform}: {'✅' if ok else '❌'} {msg}")

Supported Browser Identifiers

The extract_all() function accepts the following string identifiers:

• chrome
• firefox
• edge
• brave
• opera

Summary

• Dual Backend Design: Agent Reach prefers the Rust-based rookiepy for speed and reliability, falling back to browser_cookie3 when unavailable.
• Declarative Filtering: The PLATFORM_SPECS static registry in agent_reach/cookie_extract.py defines exactly which domains and cookie names each social platform requires.
• Persistent Storage: The configure_from_browser() function writes extracted tokens to ~/.agent_reach.yaml via the Config class, with additional syncs to legacy session files.
• Broad Browser Support: Chrome, Firefox, Edge, Brave, and Opera are supported through both backend libraries.
• CLI Integration: Both agent-reach install and agent-reach configure --from-browser automate the extraction workflow without requiring Python scripting.

Frequently Asked Questions

What browsers does Agent Reach support for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The extraction logic in agent_reach/cookie_extract.py maps these browser names to the appropriate backend helpers in either rookiepy or browser_cookie3. If you have multiple browsers installed, the CLI defaults to Chrome first, then automatically tries Firefox if no authentication cookies are found.

Why does Agent Reach use rookiepy instead of just browser_cookie3?

rookiepy is the preferred backend because it is written in Rust and provides faster, more reliable access to modern browser encryption formats like Chromium's AES-256-GCM cookie stores. However, because rookiepy requires a Rust compilation environment, Agent Reach gracefully falls back to the pure-Python browser_cookie3 library if the import fails, ensuring maximum portability across different deployment environments.

Where does Agent Reach store the cookies after extraction?

Extracted cookies are written to ~/.agent_reach.yaml via the Config class in agent_reach/config.py. The configure_from_browser() function additionally creates auxiliary files like credentials.env for the bird CLI and updates legacy xfetch session files where applicable. This persistence layer ensures that downstream channel modules can access authentication tokens without repeatedly querying the browser's SQLite databases.

Can I extract cookies for platforms not defined in PLATFORM_SPECS?

No. The current implementation strictly filters against the static PLATFORM_SPECS list defined in agent_reach/cookie_extract.py. To support a new platform, you must modify the source code to add an entry containing the name, domains, required cookies (or None for full serialization), and a unique config_key. Without this registry entry, the extraction logic will ignore cookies for that domain even if they exist in your browser.

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