How to Configure Twitter Authentication with Cookies in Agent Reach

Agent Reach extracts browser cookies for Twitter/X authentication and stores them in ~/.agent-reach/config.yaml or environment variables, enabling AI agents to perform read and search operations through multiple back-ends including twitter-cli and OpenCLI.

Agent Reach is a Python framework that provides AI agents with read-search access to web platforms. When you configure Twitter authentication with cookies in Agent Reach, the system pulls session tokens directly from your browser and validates them against installed CLI tools before routing requests.

Understanding Agent Reach Twitter Back-Ends

Agent Reach supports three back-ends for Twitter/X integration, discovered dynamically in agent_reach/channels/twitter.py (lines 14-34):

• twitter-cli – Probed via Channel.check() by running twitter status and inspecting output.
• OpenCLI – Detected through self._check_opencli() which verifies server readiness via opencli_status.
• bird (legacy) – Validated by calling bird check (or birdx) and examining the result.

When TwitterChannel.check() confirms a back-end reports ok status, all subsequent read() and search() calls route through that provider.

Where Credentials Are Stored

Agent Reach centralizes authentication in agent_reach/config.py with three fallback layers:

Configuration file – ~/.agent-reach/config.yaml stores twitter_auth_token and twitter_ct0 (legacy key names used by the twitter-cli back-end).

Environment variables – The Config.get() method falls back to uppercase environment variables, so TWITTER_AUTH_TOKEN and TWITTER_CT0 override file settings without modifying YAML.

Browser cookie extraction – agent_reach/cookie_extract.py implements configure_from_browser(), which reads auth_token and ct0 from Chrome, Firefox, Edge, Brave, or Opera stores via rookiepy or browser-cookie3. This function synchronizes credentials to legacy locations used by twitter-cli (~/.config/xfetch/session.json) and bird (~/.config/bird/credentials.env).

Auto-Configure from Browser

The fastest method extracts cookies automatically using the CLI entry point in agent_reach/cli.py (lines 1070-1085):

python -m agent_reach.cli configure --from-browser chrome

This invokes cookie_extract.configure_from_browser('chrome', config), which:

1. Extracts auth_token and ct0 from Chrome's cookie store.
2. Writes values to ~/.agent-reach/config.yaml.
3. Syncs to legacy XFetch and bird configuration paths for compatibility.

Manual Configuration with Environment Variables

For CI/CD pipelines or temporary sessions, export tokens directly:

export TWITTER_AUTH_TOKEN="your-auth-token-here"
export TWITTER_CT0="your-ct0-value-here"

# Verify the channel detects credentials

python -m agent_reach.cli doctor

When TwitterChannel.check() detects these variables via config.get("twitter_auth_token"), it reports ok and selects the highest-priority installed back-end.

Programmatic Access

Use the Python API to search and read tweets after configuration:

from agent_reach.core import AgentReach
from agent_reach.config import Config

cfg = Config()  # loads ~/.agent-reach/config.yaml

ar = AgentReach(config=cfg)

# Search Twitter (routes to active back-end)

results = ar.search("site:x.com \"large language model\"")
print(results)

# Read specific tweet

tweet = ar.read("https://x.com/elonmusk/status/123456789")
print(tweet)

AgentReach delegates to TwitterChannel.read() and search(), which internally call the chosen back-end CLI.

Verify and Inspect Configuration

Check stored credentials without exposing full secrets using the masking feature in config.py (lines 108-130):

from agent_reach.config import Config

cfg = Config()
print(cfg.to_dict())  # Shows only first 8 characters of tokens

The to_dict() method masks any key containing "auth", "token", or "ct0", allowing safe debugging.

Summary

• Three back-ends supported: twitter-cli, OpenCLI, and bird (legacy), auto-discovered in agent_reach/channels/twitter.py.
• Cookie extraction: configure_from_browser() in agent_reach/cookie_extract.py pulls tokens from major browsers and syncs to legacy config paths.
• Storage hierarchy: Cookies live in ~/.agent-reach/config.yaml under twitter_auth_token and twitter_ct0, with fallback to TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables.
• Validation: Run python -m agent_reach.cli doctor to confirm TwitterChannel.check() reports ok before executing searches.

Frequently Asked Questions

What browsers are supported for cookie extraction?

Agent Reach supports Chrome, Firefox, Edge, Brave, and Opera. The configure_from_browser() function in agent_reach/cookie_extract.py uses rookiepy or browser-cookie3 to read cookie stores from default profiles on all major platforms.

Why does Agent Reach require both auth_token and ct0 cookies?

These tokens represent Twitter/X session authentication (auth_token) and CSRF protection (ct0). The twitter-cli back-end requires both values to execute authenticated requests, which Agent Reach stores under the legacy key names twitter_auth_token and twitter_ct0 for compatibility.

Can I use Agent Reach without installing twitter-cli or bird?

Yes. If you have OpenCLI installed and running, Agent Reach will detect it via opencli_status() in agent_reach/backends/opencli.py and route requests through that back-end instead. The authentication credentials work across all three supported back-ends.

Is it safe to commit the Agent Reach config file to version control?

No. While Config.to_dict() masks secrets when printing, the raw YAML file at ~/.agent-reach/config.yaml contains full session tokens. Add this path to .gitignore and use environment variables in production environments to avoid credential leakage.

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