How Agent Reach `configure --from-browser` Parses and Stores Cookies

The agent-reach configure --from-browser command extracts authentication cookies from Chrome, Firefox, Edge, Brave, or Opera using the rookiepy or browser_cookie3 libraries, filters them against platform-specific patterns via extract_all(), and persists them to ~/.agent-reach/config.yaml using the configure_from_browser function in agent_reach/cookie_extract.py.

The configure --from-browser option in Agent Reach automates the extraction of session cookies from popular web browsers to authenticate with social media platforms. When you run this command, the CLI delegates the heavy lifting to specialized extraction modules that read browser storage, filter cookies by domain, and persist the credentials to a YAML-based configuration file. This eliminates manual copy-pasting of cookie strings and ensures compatibility with the tool's various platform adapters.

CLI Entry Point and Delegation

In agent_reach/cli.py, the --from-browser flag triggers a call to configure_from_browser() from the agent_reach.cookie_extract module. This function accepts a browser name (e.g., chrome, firefox) and a Config instance, orchestrating the entire extraction and storage workflow.

The CLI supports five browsers: Chrome, Firefox, Edge, Brave, and Opera. You invoke the command as follows:

# Extract cookies from Chrome

agent-reach configure --from-browser chrome

# Extract cookies from Firefox

agent-reach configure --from-browser firefox

The Cookie Extraction Pipeline

Browser Library Abstraction

The extract_all() function in agent_reach/cookie_extract.py handles the low-level browser access. It attempts to import rookiepy first, falling back to browser_cookie3 if unavailable. The function opens the browser's cookie store and reads every cookie, wrapping them in lightweight _Cookie objects containing name, value, and domain attributes.

Platform-Specific Filtering with PLATFORM_SPECS

After extraction, the code filters cookies using a static PLATFORM_SPECS table that maps platforms to their required domain patterns and cookie names. The logic processes each cookie as follows:

• Domain matching: If a cookie's domain matches a platform's pattern, it is collected for that platform.
• Header string platforms: For XiaoHongShu and Xueqiu, matching cookies are concatenated into a "name=value; ..." string.
• Named cookie platforms: For Twitter/X and Bilibili, the function extracts specific cookie names (auth_token, ct0, SESSDATA, bili_jct) into a dictionary.

The result is a structured dictionary mapping platform names to their authentication data:

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

Configuration Persistence and Storage

The configure_from_browser function receives the filtered extraction results and a Config instance (the central YAML-based configuration manager). It then writes platform-specific values to ~/.agent-reach/config.yaml and generates legacy compatibility files for downstream tools.

Twitter/X Authentication

For Twitter/X, the function saves auth_token to the twitter_auth_token key and ct0 to twitter_ct0. It also writes a legacy xfetch session file to ~/.config/xfetch/session.json and a bird environment file to ~/.config/bird/credentials.env to maintain compatibility with external tooling.

XiaoHongShu Header Strings

The entire concatenated cookie string for XiaoHongShu is stored under the key xhs_cookie in the YAML configuration.

Bilibili Token Storage

For Bilibili, SESSDATA is saved to bilibili_sessdata, and if present, bili_jct is saved to bilibili_csrf for CSRF token validation.

Xueqiu Validation

Xueqiu cookies are only stored if the header string contains the required xq_a_token. The resulting string is saved under xueqiu_cookie.

Each operation returns a status tuple: ("Platform Name", True, "description") for success or ("Platform Name", False, "error message") for failure, enabling the CLI to render a tidy status table.

Practical Usage Examples

You can interact with the cookie extraction programmatically using the Python API:

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

cfg = Config()
results = configure_from_browser('chrome', cfg)

# Access stored credentials

print(cfg.get('twitter_auth_token'))  # AAAAAAAAAAAAAAAAAAAAAA...

print(cfg.get('xhs_cookie'))          # xsid=abc123; xhsid=def456; ...

The results list contains status tuples for each platform:

[('Twitter/X', True, 'auth_token + ct0'),
 ('XiaoHongShu', True, '5 cookies'),
 ('Bilibili', True, 'SESSDATA + bili_jct'),
 ('Xueqiu', False, '找到 3 个 Cookie 但缺少 xq_a_token，...')]

Summary

• Entry point: The --from-browser flag in agent_reach/cli.py delegates to configure_from_browser().
• Extraction: Uses rookiepy (preferred) or browser_cookie3 via extract_all() to read browser cookies into _Cookie objects.
• Filtering: PLATFORM_SPECS maps domains and selects specific cookies or header strings for Twitter/X, XiaoHongShu, Bilibili, and Xueqiu.
• Storage: Saves to ~/.agent-reach/config.yaml with keys like twitter_auth_token, xhs_cookie, and bilibili_sessdata.
• Legacy support: Generates ~/.config/xfetch/session.json and ~/.config/bird/credentials.env for Twitter/X tokens.

Frequently Asked Questions

Which browsers does Agent Reach support for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The extract_all() function in agent_reach/cookie_extract.py attempts to use rookiepy first, then falls back to browser_cookie3 to access the browser's native cookie storage.

What happens if a required cookie is missing for a specific platform?

If required cookies are missing (for example, if Xueqiu lacks xq_a_token), the function returns a failure tuple with a descriptive message like ('Xueqiu', False, '找到 3 个 Cookie 但缺少 xq_a_token'). The CLI displays this as a failed status in the output table, and no configuration is written for that platform.

Where does Agent Reach store the extracted cookies?

Credentials are persisted to ~/.agent-reach/config.yaml via the Config class. Platform-specific keys include twitter_auth_token, twitter_ct0, xhs_cookie, bilibili_sessdata, bilibili_csrf, and xueqiu_cookie.

Why does Agent Reach create files in ~/.config/xfetch and ~/.config/bird?

These are legacy compatibility files generated specifically for Twitter/X authentication. When processing Twitter cookies, configure_from_browser() writes ~/.config/xfetch/session.json and ~/.config/bird/credentials.env to ensure seamless integration with the xfetch and bird downstream tools that expect credentials in those specific locations.

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