How to Configure Twitter/X Authentication in Agent Reach: Cookie-Editor Export and Manual Setup Guide

Agent Reach stores Twitter/X credentials by extracting the auth_token and ct0 cookies from a Cookie-Editor export and saving them to ~/.agent-reach/config.yaml with restricted permissions.

Configuring Twitter/X authentication in the Panniantong/Agent-Reach framework requires capturing two specific session cookies that X (formerly Twitter) uses to maintain login state. The tool provides a streamlined CLI workflow that accepts multiple input formats—from raw browser exports to manual token entry—and automatically secures these credentials for downstream tools like twitter-cli or OpenCLI.

Understanding the Authentication Mechanism

Agent Reach relies on two specific cookies to authenticate with X's API: auth_token and ct0. These session tokens are generated when you log into X via a web browser and remain valid for extended periods.

According to the source code in agent_reach/cookie_extract.py (lines 18-22), the framework defines a specific extraction specification for Twitter that targets these exact cookie names. When present, these values allow the TwitterChannel implementation in agent_reach/channels/twitter.py (lines 84-88) to probe the twitter-cli backend and verify active sessions.

Prerequisites: Extracting Cookies from Your Browser

Before configuring Agent Reach, you must export the active cookies from your browser session. The recommended approach uses the Cookie-Editor extension available for Chrome, Edge, or Firefox.

1. Install Cookie-Editor from your browser's extension store.
2. Navigate to x.com or twitter.com and ensure you are logged in.
3. Open Cookie-Editor and click Export.
4. Choose either Export as Header (creates a string like auth_token=...; ct0=...) or Export as JSON (creates an array of cookie objects).

Configuration Methods

Agent Reach supports three input formats through the agent-reach configure twitter-cookies command, implemented in agent_reach/cli.py (lines 50-61).

Method 1: Using Cookie-Editor Header String Export

Paste the semicolon-separated header string directly into the CLI. This is the fastest method if you copied the "Export as Header" format from Cookie-Editor.

agent-reach configure twitter-cookies "auth_token=AAAAAAAAAAAAAAAAAAAA; ct0=BBBBBBBBBBBBBBBBBBBB"

The _parse_twitter_cookie_input function (lines 32-49 in agent_reach/cli.py) detects the auth_token= and ct0= substrings and parses the values automatically.

Method 2: Using Cookie-Editor JSON Export

If you exported a JSON array from Cookie-Editor, pass the raw JSON string. This format preserves domain metadata and is useful for complex multi-domain exports.

agent-reach configure twitter-cookies '[{"name":"auth_token","value":"AAAAAAAAAAAAAAAAAAAA","domain":".x.com"},{"name":"ct0","value":"BBBBBBBBBBBBBBBBBBBB","domain":".x.com"}]'

The parser validates the JSON structure and extracts the value fields for the two required cookies.

Method 3: Manual Space-Separated Input

For manual setup without browser extensions, provide the raw token values separated by a space. This bypasses parsing logic and stores the values directly.

agent-reach configure twitter-cookies "AAAAAAAAAAAAAAAAAAAA BBBBBBBBBBBBBBBBBBBB"

How the CLI Parses and Stores Cookies

When you run the configuration command, Agent Reach executes a specific storage workflow defined in the source code.

Parsing logic: The _parse_twitter_cookie_input function in agent_reach/cli.py (lines 32-49) handles three scenarios:

• Header string: Detects ; delimiters and = assignments to extract key-value pairs.
• JSON array: Parses the structure and iterates to find matching cookie names.
• Space-separated tokens: Treats the first token as auth_token and the second as ct0.

Storage security: The parsed values are passed to Config.set (lines 56-58), which writes to ~/.agent-reach/config.yaml. As implemented in agent_reach/config.py (lines 49-66), the configuration file is created with 0600 permissions, ensuring only the owner can read the sensitive tokens.

Environment fallback: The Config class (lines 70-78) automatically falls back to environment variables TWITTER_AUTH_TOKEN and TWITTER_CT0 if the config file is absent, providing flexibility for CI/CD pipelines.

Verification and Health Checks

After configuration, verify that the credentials work with the built-in health check.

agent-reach doctor

The TwitterChannel.check method in agent_reach/channels/twitter.py (lines 20-52) executes a test command using the stored cookies. If the twitter-cli status command returns "ok: true" (lines 78-80), the output displays:

Twitter/X  ✔  twitter-cli (ok: true)

You can also inspect the stored configuration directly:

cat ~/.agent-reach/config.yaml

The output should contain:

twitter_auth_token: AAAAAAAAAAAAAAAAAAAA
twitter_ct0: BBBBBBBBBBBBBBBBBBBB

Summary

• Agent Reach requires the auth_token and ct0 cookies from X to authenticate API requests.
• The CLI accepts header strings, JSON arrays, or space-separated tokens via agent-reach configure twitter-cookies.
• Credentials are stored in ~/.agent-reach/config.yaml with 0600 file permissions for security.
• The TwitterChannel implementation probes twitter-cli using environment variables derived from the stored config.
• Use agent-reach doctor to verify that the extracted cookies are valid and functional.

Frequently Asked Questions

What are the auth_token and ct0 cookies used for in Agent Reach?

The auth_token is the primary session identifier for your X account, while ct0 is a cross-site request forgery (CSRF) token required for authenticated API calls. Agent Reach extracts these specific values in agent_reach/cookie_extract.py (lines 44-53) because the twitter-cli backend expects them as environment variables to execute commands on your behalf.

Can I configure Twitter authentication without using Cookie-Editor?

Yes. While Cookie-Editor is the recommended tool for exporting browser cookies, you can manually obtain the cookie values from your browser's developer tools (Application/Storage tab) and pass them as space-separated values: agent-reach configure twitter-cookies "TOKEN1 TOKEN2". The CLI parser treats two space-separated tokens as raw auth_token and ct0 values.

How does Agent Reach secure my Twitter credentials?

The framework writes configuration data to ~/.agent-reach/config.yaml using file mode 0600, meaning only the file owner has read and write permissions. This implementation in agent_reach/config.py (lines 49-66) prevents other system users from accessing your authentication tokens. Additionally, credentials can be overridden via environment variables, allowing you to avoid persistent disk storage in shared environments.

Why does agent-reach doctor fail even after configuring cookies?

The health check fails if the stored cookies are expired, invalid, or if twitter-cli is not installed in your PATH. The TwitterChannel.check method (lines 20-52 in agent_reach/channels/twitter.py) runs a status probe that must return "ok: true". If you recently changed your X password or logged out of sessions remotely, the auth_token becomes invalid and you must export fresh cookies from your browser.

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