How Agent-Reach Extracts and Secures Browser Cookies for Twitter/X and XiaoHongShu

Agent-Reach reads your local browser's cookie store, filters platform-specific authentication tokens for Twitter/X and XiaoHongShu, and writes them to a permission-locked YAML configuration file at ~/.agent-reach/config.yaml while maintaining compatibility with legacy CLI tools.

Agent-Reach is an open-source automation framework designed for social media platform interactions. Handling authentication credentials securely is critical when automating platforms like Twitter/X and XiaoHongShu, which is why the project implements a robust pipeline to extract and secure browser cookies directly from your local browser stores.

Cookie Extraction Architecture

The extraction logic resides in agent_reach/cookie_extract.py and implements a two-tier fallback strategy for browser compatibility.

Browser Library Abstraction

The extract_all() function attempts to use the Rust-based rookiepy library first, falling back to browser-cookie3 if the import fails. Both libraries expose browser-specific functions (chrome, firefox, edge, brave, opera) that return iterable cookie objects containing name, value, and domain attributes.

Platform Specification Mapping

The PLATFORM_SPECS constant (lines 13-39) defines domain patterns and required cookie names for each supported service. For Twitter/X, it targets .x.com and .twitter.com domains, extracting specific cookies named auth_token and ct0. For XiaoHongShu, it filters for .xiaohongshu.com domains.

Domain Filtering and Token Extraction

Inside extract_all(), the code iterates through every cookie returned by the browser library. It checks whether cookie.domain ends with any domains declared for the target platform. When a platform's cookies list is defined (as with Twitter/X), only those specific names are retained; otherwise, the entire cookie set is concatenated into a header-style string (XiaoHongShu).

The function returns a dictionary keyed by the platform's config_key (twitter or xhs). For Twitter/X, this contains individual key-value pairs for auth_token and ct0. For XiaoHongShu, it contains a single cookie_string entry with the full header-formatted value.

Secure Configuration Persistence

Once extracted, configure_from_browser() calls extract_all() and writes values to the central Config object using config.set(). Twitter tokens are stored under twitter_auth_token and twitter_ct0, while XiaoHongShu data is saved under xhs_cookie.

File Permission Locking

The Config.save() method in agent_reach/config.py (lines 52-66) creates the configuration file with mode 0o600 (owner read/write only) using os.open and os.chmod. This guarantees that extracted browser cookies are never world-readable on disk.

Legacy Tool Compatibility

Agent-Reach synchronizes credentials with existing tools that expect specific formats.

xfetch Session Synchronization

The _sync_xfetch_session() function writes a JSON file to ~/.config/xfetch/session.json containing authToken and ct0 keys, mirroring the historic xfetch format (lines 76-98).

Bird CLI Environment Variables

The _sync_bird_env() helper generates a shell-sourceable credentials.env file under ~/.config/bird/, exporting AUTH_TOKEN and CT0 variables with safely quoted values using shlex.quote (lines 104-122).

Command-Line and Programmatic Usage

Users can trigger the extraction pipeline via CLI or Python API.

CLI Invocation

agent-reach configure --from-browser chrome

This command internally calls cookie_extract.configure_from_browser() and handles the full extraction-to-storage workflow.

Python API

from agent_reach.cookie_extract import extract_all

# Extract cookies from Chrome

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

# Output:

# {

#   "twitter": {"auth_token": "...", "ct0": "..."},

#   "xhs": {"cookie_string": "a=1; b=2; ..."},

# }

Manual Configuration Fallback

When automatic extraction fails, the repository provides a manual guide at docs/cookie-export.md explaining how to export cookie header strings directly from browser DevTools and paste them into the CLI.

Summary

• Agent-Reach extracts browser cookies using a dual-library approach (rookiepy with browser-cookie3 fallback) to support Chrome, Firefox, Edge, Brave, and Opera.
• Platform specifications in PLATFORM_SPECS define domain patterns (.x.com, .twitter.com, .xiaohongshu.com) and required cookie names for targeted extraction.
• Security is enforced through 0o600 file permissions on ~/.agent-reach/config.yaml, ensuring only the owner can read stored authentication tokens.
• Legacy compatibility maintains synchronisation with xfetch JSON sessions and Bird CLI environment variables through dedicated sync functions.
• Multiple interfaces support both CLI (--from-browser) and Python API (extract_all()) workflows, with manual export documentation as a fallback.

Frequently Asked Questions

How does Agent-Reach handle different browser types?

The extract_all() function in agent_reach/cookie_extract.py implements a dual-library strategy, attempting the Rust-based rookiepy library first for stability and falling back to browser-cookie3 if unavailable. Both libraries provide identical interfaces for Chrome, Firefox, Edge, Brave, and Opera, yielding cookie objects with name, value, and domain attributes that the code filters by platform.

What specific cookies are extracted for Twitter/X versus XiaoHongShu?

Agent-Reach extracts auth_token and ct0 cookies from .x.com and .twitter.com domains for Twitter/X, storing them as individual values under twitter_auth_token and twitter_ct0. For XiaoHongShu, it extracts all cookies from .xiaohongshu.com and concatenates them into a single header-formatted string saved under xhs_cookie, as defined in the PLATFORM_SPECS constant.

How does Agent-Reach secure stored cookies on disk?

The Config.save() method in agent_reach/config.py creates the configuration file using os.open with mode 0o600 (owner read/write only) and applies os.chmod to enforce these permissions. This ensures that even if other users have filesystem access to the machine, they cannot read the extracted browser cookies from ~/.agent-reach/config.yaml.

Can I use the extracted cookies with other tools?

Yes, Agent-Reach maintains backward compatibility through _sync_xfetch_session(), which writes credentials to ~/.config/xfetch/session.json for legacy xfetch support, and _sync_bird_env(), which generates ~/.config/bird/credentials.env with shell-safe quoting via shlex.quote. These synchronization functions ensure seamless integration with existing CLI tools that expect specific credential formats.

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