How Agent-Reach Extracts Browser Cookies Using the --from-browser Flag

Agent-Reach's --from-browser flag triggers a secure pipeline that reads authentication cookies directly from your browser's SQLite or encrypted stores using rookiepy or browser-cookie3, filters them by platform-specific domain patterns, and injects them into the tool's YAML configuration with owner-only file permissions.

Agent-Reach is an open-source automation framework that eliminates manual cookie copy-pasting by importing authentication tokens directly from your browser. When you run the configure command with the --from-browser flag, the tool executes a multi-stage extraction process that maps browser cookies to platform-specific configuration keys for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.

CLI Argument Parsing and Dispatch

The command-line interface defines the --from-browser argument within the configure subcommand group in [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L125-L130). When this flag is present, the Cli.configure() method delegates execution to the cookie extraction module.

# From agent_reach/cli.py

if args.from_browser:
    # Delegates to cookie_extract.configure_from_browser()

    self.configure_from_browser(args)

This dispatch triggers the core extraction routine configure_from_browser(browser, config) located in agent_reach/cookie_extract.py, which orchestrates the entire import process.

The Cookie Extraction Architecture

Platform Specification Mapping

Before reading any browser data, Agent-Reach consults the PLATFORM_SPECS dictionary defined at the top of [agent_reach/cookie_extract.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py#L13-L39). This structure maps supported platforms to their domain patterns and required cookie names:

• Twitter/X: Requires auth_token and ct0 cookies from .twitter.com
• XiaoHongShu: Requires all cookies from .xiaohongshu.com formatted as a header string
• Bilibili: Requires SESSDATA from .bilibili.com
• Xueqiu: Requires all cookies from .xueqiu.com formatted as a header string

Reading Browser Storage

The extract_all() function handles low-level browser access. It attempts to import rookiepy first—a high-performance Rust-based wrapper—and falls back to browser-cookie3 if unavailable. Depending on the specified browser (Chrome, Firefox, Edge, Brave, or Opera), it calls the corresponding library function:

# Conceptual flow from extract_all()

if browser == "chrome":
    cookies = rookiepy.chrome()  # or browser_cookie3.chrome()

These libraries decrypt the browser's SQLite stores or use OS keyring access to return cookie objects exposing .name, .value, and .domain attributes.

Filtering and Normalization

Agent-Reach iterates through the raw cookie list and applies the PLATFORM_SPECS filters. For platforms with explicit cookie lists like Twitter, it extracts only the named tokens. For platforms requiring full header strings like XiaoHongShu, it concatenates all matching cookies into a semicolon-delimited string (name1=val1; name2=val2).

The function returns a structured dictionary keyed by platform identifiers (e.g., "twitter", "xhs") containing the extracted values, as implemented in lines 44-52 and lines 114-145.

Configuration Integration and Persistence

Updating Agent-Reach Config

Back in configure_from_browser(), the extracted dictionary is applied to the Config object via config.set() calls:

• config.set("twitter_auth_token", value)
• config.set("twitter_ct0", value)
• config.set("xhs_cookie", value)
• config.set("bilibili_sessdata", value)
• config.set("xueqiu_cookie", value)

These calls update the user's ~/.agent-reach/config.yaml file with the fresh authentication tokens.

Legacy Tool Synchronization

Agent-Reach performs best-effort synchronization to legacy helper tools (xfetch and bird) by writing additional configuration files. This includes creating a JSON metadata file and a private .env file containing the tokens, ensuring compatibility with external scripts without breaking the main configuration flow (see lines 76-98).

Security and File Permissions

All file write operations utilize the _open_owner_only() helper to enforce 0600 permissions (owner read/write only) on created files. This prevents accidental exposure of sensitive authentication tokens to other system users, as implemented in lines 49-70.

Practical Usage Examples

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

agent-reach configure --from-browser chrome

Use Firefox instead:

agent-reach configure --from-browser firefox

Programmatic usage bypassing the CLI:

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

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

status = configure_from_browser("chrome", cfg)

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

Summary

• The --from-browser flag is parsed in agent_reach/cli.py and triggers configure_from_browser().
• Extraction relies on rookiepy (preferred) or browser-cookie3 to read encrypted browser stores.
• PLATFORM_SPECS defines domain patterns for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• Cookies are filtered, shaped into platform-specific structures, and injected via config.set().
• Legacy tool sync and 0600 file permissions ensure secure, backwards-compatible storage.

Frequently Asked Questions

Which browsers are supported by the --from-browser flag?

Agent-Reach supports Chrome, Firefox, Edge, Brave, and Opera. The underlying rookiepy or browser-cookie3 libraries handle the specific decryption mechanisms for each browser's cookie storage format.

What happens if neither rookiepy nor browser-cookie3 is installed?

If both libraries are unavailable, extract_all() raises an ImportError with instructions to install one of the dependencies. The extraction cannot proceed without one of these backends to handle browser-specific encryption.

Is the cookie extraction process secure?

Yes. Agent-Reach only reads cookies from your local browser stores and never transmits them over the network. Written configuration files are created with 0600 permissions using _open_owner_only(), ensuring only your user account can read the extracted tokens.

Why does the output show "manual login required" for some platforms?

This message appears when the browser cookie store lacks the specific tokens required by a platform's PLATFORM_SPECS definition. For example, if you haven't logged into XiaoHongShu in the specified browser recently, those cookies won't exist, and Agent-Reach cannot extract them automatically.

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