How Agent-Reach Extracts Browser Cookies with `--from-browser`: A Technical Deep Dive

Agent-Reach's --from-browser flag triggers a multi-stage pipeline that reads authentication cookies directly from Chrome, Firefox, Edge, Brave, or Opera using rookiepy or browser-cookie3, filters them by platform-specific domain patterns, and automatically injects them into the configuration file with secure 0600 permissions.

Agent-Reach simplifies social media automation by allowing users to import existing browser sessions via the --from-browser CLI option. This feature eliminates manual cookie copying by extracting tokens directly from the browser's local storage and mapping them to the correct configuration keys. Understanding this mechanism requires examining the interaction between the CLI parser, the cookie extraction module, and the platform-specific filtering logic implemented in the source code.

Architecture of the --from-browser Pipeline

CLI Argument Parsing

The command-line interface defines the --from-browser flag within the configure subcommand. In agent_reach/cli.py, the argument parser accepts this flag between lines 125-130, specifying the target browser name (e.g., chrome, firefox). When the configure action is invoked, the method checks for args.from_browser and initiates the extraction sequence by calling the cookie extraction module.

Extraction Entry Point

The configure_from_browser(browser, config) function in agent_reach/cookie_extract.py (lines 32-38) serves as the primary orchestrator. This function accepts a browser identifier and a Config object, then coordinates the entire extraction workflow. It first invokes extract_all(browser) to retrieve raw cookie data, then processes the results to populate the configuration object, and finally returns a status list detailing success or failure for each supported platform.

How Cookies Are Extracted and Processed

Reading Browser Cookie Stores

The extraction layer attempts to use rookiepy first—a Rust-based library that provides reliable access to browser cookie databases—and falls back to browser-cookie3 if the former is unavailable (lines 53-66). For the specified browser, the code executes the appropriate retrieval function (e.g., rookiepy.chrome() or browser_cookie3.firefox()), which yields cookie objects exposing .name, .value, and .domain attributes.

Platform-Specific Filtering

The extraction logic relies on the PLATFORM_SPECS dictionary defined at the top of agent_reach/cookie_extract.py (lines 13-39). This structure maps platform identifiers to their domain patterns and required cookie names for Twitter/X, XiaoHongShu (XHS), Bilibili, and Xueqiu.

The filtering process iterates over every retrieved cookie and:

• Matches the cookie's domain against platform-specific patterns (e.g., .twitter.com, .xiaohongshu.com)
• For Twitter and Bilibili, extracts specific named cookies (auth_token, ct0, SESSDATA)
• For XiaoHongShu and Xueqiu, constructs a combined cookie_string in the format name1=val1; name2=val2 from all cookies matching the domain

The results are assembled into a dictionary keyed by platform identifiers (twitter, xhs, bilibili, xueqiu) and returned to the caller (lines 44-52 and 114-145).

Configuration Integration and Legacy Sync

Once extracted, the credentials are applied to the Agent-Reach configuration through specific setter methods. For Twitter credentials, the system stores twitter_auth_token and twitter_ct0 via config.set() calls, then syncs these tokens to legacy tools (xfetch and bird) by writing a JSON file and a private .env file in the user's configuration directory (lines 76-98).

For other platforms, the values are stored directly in the Agent-Reach YAML configuration:

• XiaoHongShu: xhs_cookie
• Bilibili: bilibili_sessdata
• Xueqiu: xueqiu_cookie (lines 66-88 and 73-81)

Security and File Permissions

All credential file writes utilize the _open_owner_only() helper to ensure newly created files receive 0600 permissions (owner read/write only), preventing accidental exposure of sensitive tokens to other system users (lines 49-70).

Practical Implementation Examples

Command-Line Usage

Extract cookies from Chrome (default) and configure all detected platforms:

agent-reach configure --from-browser chrome

Use Firefox instead:

agent-reach configure --from-browser firefox

Programmatic Access

you can invoke the same logic programmatically without the CLI:

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

# Load existing configuration

cfg = Config()  # Loads ~/.agent-reach/config.yaml

# Extract from Chrome and apply

status = configure_from_browser("chrome", cfg)

# Review results

for platform, success, message in status:
    indicator = "✅" if success else "❌"
    print(f"{platform}: {indicator} – {message}")

Key Files and Implementation Details

File	Role	Source Reference
agent_reach/cli.py	Parses --from-browser argument and dispatches to extraction logic	Lines 125-130
agent_reach/cookie_extract.py	Core extraction logic, platform specifications, and configuration integration	Lines 32-38, Lines 13-39
agent_reach/config.py	Handles YAML configuration persistence and value retrieval	Implicitly called by configure_from_browser
agent_reach/utils/paths.py	Provides make_private_dir and permission utilities used by _open_owner_only	Referenced in extraction logic

Summary

• Agent-Reach provides seamless cookie extraction via the --from-browser CLI flag, supporting Chrome, Firefox, Edge, Brave, and Opera.
• The extraction pipeline uses rookiepy with a browser-cookie3 fallback to read browser databases directly from the filesystem.
• Platform-specific filtering in PLATFORM_SPECS ensures only relevant authentication tokens are extracted for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• Extracted credentials are written to the Agent-Reach configuration file with strict 0600 permissions, and Twitter tokens are additionally synced to legacy helper tools.
• The entire process is encapsulated in the configure_from_browser() function, which returns detailed status information for each platform.

Frequently Asked Questions

Which browsers are supported by --from-browser?

Agent-Reach supports Chrome, Firefox, Edge, Brave, and Opera. The underlying rookiepy and browser-cookie3 libraries handle the specific database locations and formats for each browser across Windows, macOS, and Linux operating systems.

What happens if rookiepy is not installed?

The extraction logic automatically falls back to browser-cookie3 if rookiepy is unavailable in the Python environment. This fallback occurs in the extract_all() function within agent_reach/cookie_extract.py, ensuring the feature remains functional regardless of which library is present.

How does Agent-Reach secure extracted cookies?

All credential files are created using the _open_owner_only() helper, which sets file permissions to 0600 (readable and writable only by the owner). This prevents other users on the system from accessing sensitive authentication tokens stored in the configuration directory.

Can I extract cookies programmatically without using the CLI?

Yes. The configure_from_browser(browser, config) function in agent_reach/cookie_extract.py is designed for programmatic use. You can instantiate a Config object, pass it along with a browser name (e.g., "chrome"), and receive a list of tuples containing (platform, success, message) for each configured service.

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