Agent Reach Platform Authentication Using Cookies: Complete Technical Guide

TLDR: Agent Reach extracts browser-stored cookies for platforms like Twitter/X, XiaoHongShu, and Bilibili, storing them in ~/.agent-reach/config.yaml to enable AI agent access without password prompts.

Agent Reach is a CLI glue layer that enables AI agents to interact with web platforms requiring logged-in sessions. Instead of requesting user passwords, the tool implements Agent Reach platform authentication using cookies extracted directly from your browser's cookie store. This approach maintains security while providing seamless access to platforms like Twitter/X, XiaoHongShu, Bilibili, and Xueqiu according to the Panniantong/Agent-Reach source code.

Architecture of the Cookie Authentication System

The authentication flow operates through three integrated layers that handle extraction, persistence, and runtime consumption of session credentials.

Cookie Extraction Layer

In agent_reach/cookie_extract.py, the extract_all(browser: str) function loads the selected browser’s cookie store using the Rust-based rookiepy library, falling back to browser-cookie3 if unavailable. The function references PLATFORM_SPECS to identify which domains and cookie names are required for each platform. For platforms requiring all cookies (like XiaoHongShu), it constructs a proper HTTP header string in the format name=value; …. The function returns a dictionary keyed by platform config keys such as twitter, xhs, bilibili, and xueqiu.

Configuration Management

The configuration flow begins in agent_reach/cli.py where _cmd_configure processes the --from-browser flag. It delegates to configure_from_browser(browser, config), which writes extracted values into the central Config object defined in agent_reach/config.py. This class persists authentication data to ~/.agent-reach/config.yaml, serving as the single source of truth for the entire system.

Legacy Synchronization

For backward compatibility, the system performs platform-specific side effects. Twitter tokens are synchronized to ~/.config/xfetch/session.json and ~/.config/bird/credentials.env via _sync_xfetch_session and _sync_bird_env, enabling the upstream twitter-cli and bird tools to function. XiaoHongShu cookies are handled by _configure_xhs_cookies, which saves JSON or header strings locally or injects them into a running xiaohongshu-mcp Docker container.

Runtime Channel Integration

Channel back-ends like agent_reach/channels/twitter.py implement a check(config) method that inspects configuration via config.is_configured("twitter_xreach"). The channel verifies required keys such as twitter_auth_token and twitter_ct0 before utilizing supported back-ends including twitter-cli, OpenCLI, or bird. When performing requests, channels read stored cookie values from the Config object or auxiliary sync files and pass them to upstream tools.

Auto-Extracting Cookies from Your Browser

The fastest way to configure authentication uses the automatic extraction command:

agent-reach configure --from-browser chrome

Replace chrome with firefox, edge, brave, or opera as needed. The CLI prints a summary of extracted credentials:

✅ Twitter/X: auth_token + ct0
✅ XiaoHongShu: 12 cookies
✅ Bilibili: SE... + bili_jct
✅ Xueqiu: 8 cookies (含 xq_a_token)

This command invokes configure_from_browser to populate ~/.agent-reach/config.yaml with the extracted values.

Manual Cookie Configuration Methods

When automatic extraction fails or you prefer manual setup, the CLI supports direct cookie entry.

Twitter/X Authentication

Configure Twitter using either separate values or a full header string:

# Separate values

agent-reach configure twitter-cookies ABCDEF123456 ghijkl7890

# Full cookie header string

agent-reach configure twitter-cookies "auth_token=ABCDEF123456; ct0=ghijkl7890"

XiaoHongShu Authentication

Support both JSON export from Cookie-Editor and header strings:

# JSON format

agent-reach configure xhs-cookies '[{"name":"xhsuid","value":"12345","domain":".xiaohongshu.com"}]'

# Header string format

agent-reach configure xhs-cookies "xhsuid=12345; xhsid=67890"

Bilibili and Xueqiu Configuration

These platforms read bilibili_sessdata and optional bili_jct (Bilibili) or the Xueqiu cookie string including xq_a_token from the configuration file. Use the generic configure command or edit ~/.agent-reach/config.yaml directly to include these values.

Verifying Your Authentication Setup

Confirm proper configuration using the diagnostic tool:

agent-reach doctor --json | jq '.twitter_xreach'

A healthy configuration returns:

{
  "status": "ok",
  "message": "twitter-cli 完整可用（搜索、读推文、…）"
}

This verifies that agent_reach/channels/twitter.py or other channel implementations can successfully locate and use the stored credentials.

Summary

• Agent Reach implements cookie-based authentication by extracting browser credentials and storing them in ~/.agent-reach/config.yaml.
• The cookie extraction layer in agent_reach/cookie_extract.py uses extract_all(browser) with rookiepy or browser-cookie3 to harvest platform-specific cookies defined in PLATFORM_SPECS.
• Configuration occurs via agent-reach configure --from-browser <browser> or manual CLI commands, with _cmd_configure and configure_from_browser handling the persistence logic.
• Legacy synchronization ensures compatibility with tools like twitter-cli and bird by writing credentials to ~/.config/xfetch/session.json and ~/.config/bird/credentials.env.
• Channel back-ends consume stored cookies through the Config class, verifying availability via is_configured() before passing tokens to upstream libraries.

Frequently Asked Questions

How does Agent Reach store authentication cookies securely?

Agent Reach stores extracted cookies in a local YAML file at ~/.agent-reach/config.yaml. The tool never transmits passwords or plain-text credentials, relying instead on browser-authenticated session tokens. According to the Panniantong/Agent-Reach source code, this minimizes exposure by using existing browser authentication rather than handling raw passwords.

Can I use cookies from browsers other than Chrome?

Yes. The extract_all(browser: str) function in agent_reach/cookie_extract.py supports Firefox, Edge, Brave, and Opera in addition to Chrome. Simply specify the browser name when running agent-reach configure --from-browser <browser>. The function automatically detects the browser's cookie store location and extracts the relevant platform tokens.

What happens if cookie extraction fails?

If the Rust-based rookiepy library is unavailable, the system falls back to browser-cookie3 for cookie extraction. Should both methods fail, you can manually configure cookies using the platform-specific CLI commands (e.g., agent-reach configure twitter-cookies). The doctor command helps identify which platforms lack valid credentials.

Do I need to reconfigure cookies after browser updates?

Yes, when browser cookies expire or are cleared, you must re-run agent-reach configure --from-browser <browser> to refresh the stored tokens in ~/.agent-reach/config.yaml. Since the tool extracts current session data from your browser, any logout or cookie clearing on the browser side requires re-extraction to maintain AI agent access.

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