How to Manually Configure Twitter/X Authentication Tokens in Agent Reach

To manually configure Twitter/X authentication in Agent Reach, export the auth_token and ct0 cookie values as environment variables (TWITTER_AUTH_TOKEN and TWITTER_CT0) or use the agent-reach configure twitter-cookies CLI command to permanently store them in ~/.agent-reach/config.yaml.

Agent Reach (Panniantong/Agent-Reach) does not ship with hardcoded Twitter credentials or API keys. Instead, it authenticates with Twitter/X by injecting browser cookie values into the twitter-cli subprocess. Understanding how to manually configure these tokens ensures your agents can search and read Twitter data without hitting authentication errors.

How Twitter/X Authentication Works in Agent Reach

According to the source code in agent_reach/channels/twitter.py, the TwitterChannel class probes the backend health by executing twitter-cli status. The tool expects two specific cookie values: auth_token and ct0. When these values are present, twitter-cli returns ok: true; when missing or invalid, it returns not_authenticated.

The CLI stores these values in ~/.agent-reach/config.yaml under the keys twitter_auth_token and twitter_ct0. At runtime, Agent Reach injects these into the subprocess environment as TWITTER_AUTH_TOKEN and TWITTER_CT0 (see agent_reach/cli.py, lines 1050-1074).

Method 1: Configure via the CLI Command

The recommended approach uses the built-in configuration command to parse and store your browser cookies.

Parsing the Cookie Header

Copy the full Cookie header string from your browser's developer tools (Network tab) and pass it to the configure command:

agent-reach configure twitter-cookies "auth_token=AAA; ct0=BBB; ..."

The CLI performs three operations:

1. Parses the string to extract auth_token and ct0 values.
2. Writes them to ~/.agent-reach/config.yaml.
3. Immediately runs twitter status to verify the credentials are valid.

If the health check fails, the CLI reports the error and preserves your previous configuration.

Method 2: Export Environment Variables Manually

For temporary sessions or CI/CD pipelines, you can bypass the configuration file and export the variables directly:

export TWITTER_AUTH_TOKEN="your_auth_token_here"
export TWITTER_CT0="your_ct0_value_here"

When these environment variables are present, Agent Reach detects them automatically and passes them to twitter-cli without reading from ~/.agent-reach/config.yaml. This method is useful for testing or when you prefer not to persist credentials to disk.

Verifying Your Twitter/X Authentication

Before running agent tasks, confirm the backend is healthy.

Using the Built-in Health Check

Run the diagnostic command:

agent-reach doctor twitter

This executes the same probe found in agent_reach/channels/twitter.py (lines 82-88). A healthy output shows ok: true. If you see not_authenticated, the TwitterChannel prints the exact export commands you need to run, matching the logic in the source code.

Alternatively, test manually:

twitter status

This should return ok: true. Any other output indicates the auth_token or ct0 values are missing or expired.

How Agent Reach Injects Credentials into Subprocesses

The credential injection mechanism is implemented in agent_reach/cli.py (lines 1050-1074). When Agent Reach spawns twitter-cli, it constructs a copy of the current environment and adds the two tokens:

env = os.environ.copy()
env["TWITTER_AUTH_TOKEN"] = auth_token
env["TWITTER_CT0"] = ct0
subprocess.run([twitter_bin, "status"], env=env, ...)

This approach ensures that sensitive tokens never appear in process command lines (which are visible to other users via ps), keeping your authentication data secure.

Troubleshooting Authentication Failures

If agent-reach doctor twitter reports not_authenticated:

• Verify cookie freshness: Twitter/X cookies expire frequently. Re-export fresh auth_token and ct0 values from your browser.
• Check file permissions: Ensure ~/.agent-reach/config.yaml is readable and contains the keys twitter_auth_token and twitter_ct0.
• Validate environment variables: If using manual export, confirm TWITTER_AUTH_TOKEN and TWITTER_CT0 are set in the same shell session running Agent Reach.
• Review cli.py logic: As per agent_reach/cli.py, the configure command validates tokens immediately; if it reported success but doctor fails, the cookies likely expired between configuration and execution.

Summary

• Agent Reach requires two specific browser cookies—auth_token and ct0—to authenticate with Twitter/X via twitter-cli.
• Use agent-reach configure twitter-cookies "<header>" to permanently store credentials in ~/.agent-reach/config.yaml.
• Alternatively, export TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables for temporary access.
• The TwitterChannel class in agent_reach/channels/twitter.py validates authentication by checking for ok: true in the twitter-cli status output.
• Credentials are injected via environment variables in agent_reach/cli.py (lines 1050-1074), never passed as command-line arguments.

Frequently Asked Questions

Where does Agent Reach store Twitter credentials?

Agent Reach stores the auth_token and ct0 values in a YAML configuration file located at ~/.agent-reach/config.yaml under the keys twitter_auth_token and twitter_ct0. These values are only written to disk when you use the configure twitter-cookies CLI command; no credentials are hardcoded in the Panniantong/Agent-Reach repository.

Can I use Twitter/X API keys instead of browser cookies?

No. Agent Reach is designed specifically to work with twitter-cli, which authenticates using browser cookies (auth_token and ct0) rather than the official Twitter/X API v2 keys. This design allows the tool to access Twitter without API rate limits or developer account requirements, though it requires valid session cookies from an active browser session.

Why does Agent Reach require auth_token and ct0 specifically?

These two values are the standard session tokens that Twitter/X sets in the browser after you log in. The auth_token identifies your user session, while ct0 is a CSRF token required for API calls. The twitter-cli tool (and by extension Agent Reach) uses these to make authenticated requests on your behalf, as implemented in the health check logic in agent_reach/channels/twitter.py.

How do I export cookies from my browser for use with Agent Reach?

Open your browser's Developer Tools (F12), navigate to the Network tab, and refresh Twitter/X while logged in. Click any request to twitter.com, then view the Request Headers. Copy the entire Cookie header value, which contains auth_token and ct0. Paste this string into the agent-reach configure twitter-cookies command. For detailed visual instructions, refer to the docs/cookie-export.md file in the repository.

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