Twitter Cookie Parsing in Agent-Reach: Handling Separate Values and Full Cookie Headers

Agent-Reach's Twitter cookie parsing automatically detects whether authentication data arrives as individual environment variables or as a complete browser cookie header, normalizing both formats into a unified dictionary for downstream CLI tools.

Agent-Reach provides a flexible authentication system for Twitter/X integration that accommodates different user workflows. The repository's parsing logic, implemented primarily in agent_reach/backends/opencli_status.py, intelligently handles both individual cookie values and full header strings through automatic format detection.

Input Format Detection

The parsing routine distinguishes between input formats by checking for the presence of a semicolon separator. This simple detection mechanism allows the same function to process both styles without requiring explicit user configuration.

Separate Cookie Values

Users may export each authentication component as individual environment variables. The system specifically looks for TWITTER_AUTH_TOKEN and TWITTER_CT0, which map to the auth_token and ct0 cookies required by Twitter's API. These separate values are read by agent_reach/config.py and passed to the parsing logic for merging into a canonical format.

Full Cookie Headers

Alternatively, users can copy the entire Cookie header from their browser developer tools, typically formatted as auth_token=...; ct0=...; other=value, and paste it into a single variable. This approach supports the complete header string as provided by the browser, making it ideal for quick copy-paste workflows.

Parsing Implementation in opencli_status.py

The core parsing logic resides in agent_reach/backends/opencli_status.py. When processing input, the code executes the following steps:

1. Format Detection: Checks if the string contains a ; character. If present, the string is treated as a full cookie header; otherwise, it is processed as a single key=value pair.

2. Segmentation: For full headers, the string splits on ; with optional whitespace trimming. Each segment is isolated and cleaned to ensure proper parsing.

3. Key-Value Extraction: Each segment splits on the first = only. This design intentionally preserves any additional = characters within the value itself, which commonly occur in base64-encoded payloads.

4. Dictionary Construction: Parsed pairs populate a dict[str, str]. When separate environment variables are already present, they merge with the parsed data, with later values overwriting earlier entries to establish a single source of truth.

Validation and Environment Export

After parsing, the system validates that mandatory keys auth_token and ct0 exist in the final dictionary. If either is missing, Agent-Reach emits a warning to prompt the user for the incomplete authentication pieces.

The validated dictionary converts back into a string formatted as auth_token=...; ct0=... and exports as TWITTER_COOKIE. This guarantees that downstream commands in agent_reach/channels/twitter.py and the OpenCLI backend receive consistently formatted authentication data.

Practical Code Examples

The following examples demonstrate how Agent-Reach processes different input methods:

# Example 1: Individual environment variables

import os

os.environ["TWITTER_AUTH_TOKEN"] = "A1B2C3..."
os.environ["TWITTER_CT0"] = "XYZ987..."

# The parser reads both variables, builds:

# {"auth_token": "A1B2C3...", "ct0": "XYZ987..."}

# and exports them as a single cookie header for the backend.

# Example 2: Full cookie header from browser

import os

os.environ["TWITTER_COOKIE"] = "auth_token=A1B2C3...; ct0=XYZ987...; other=ignored"

# The parser splits on ';', trims each part, and creates:

# {"auth_token": "A1B2C3...", "ct0": "XYZ987...", "other": "ignored"}

# Missing required keys trigger a warning.

Integration with Configuration and Channels

The parsing system integrates with agent_reach/config.py, which loads environment variables and merges them with manually parsed cookie dictionaries. This unified approach feeds into agent_reach/channels/twitter.py, where the validated cookies support twitter-cli and OpenCLI authentication checks.

Summary

• Agent-Reach accepts Twitter authentication via individual variables (TWITTER_AUTH_TOKEN, TWITTER_CT0) or complete cookie headers (TWITTER_COOKIE).
• The parser in agent_reach/backends/opencli_status.py detects format by checking for ; separators and splits only on the first = to preserve base64 values.
• The system merges all inputs into a canonical dictionary, validates required keys (auth_token, ct0), and exports a standardized cookie string for downstream tools.
• This dual-format support eliminates configuration friction while ensuring consistent authentication data reaches Twitter backends.

Frequently Asked Questions

What happens if I set both separate variables and TWITTER_COOKIE?

If both individual environment variables and a full TWITTER_COOKIE string are present, Agent-Reach merges them into a single dictionary. Values from the full cookie header overwrite those from separate variables if they share the same key name, ensuring the most complete data set prevails.

How does the parser handle cookie values containing equals signs?

The splitting logic in agent_reach/backends/opencli_status.py specifically splits on the first = only. This preserves any additional = characters within the cookie value itself, which is essential for handling base64-encoded authentication tokens that frequently contain padding characters.

What are the required authentication tokens for Twitter integration?

Agent-Reach requires two specific keys: auth_token and ct0. The validation routine checks for these after parsing. If either is missing, the system emits a warning rather than failing silently, prompting you to supply the incomplete authentication pieces.

Which backend files utilize this cookie parsing logic?

The primary parsing implementation resides in agent_reach/backends/opencli_status.py. The logic is consumed by agent_reach/channels/twitter.py for Twitter-specific operations and coordinated through agent_reach/config.py, which manages the environment variable loading and merging process.

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