How to Set Up Cookie-Based Authentication for Twitter with Agent Reach

Agent Reach extracts auth_token and ct0 cookies from your browser to authenticate with Twitter, storing them in ~/.agent-reach/config.yaml or reading them from TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables to enable AI agent access.

Agent Reach is a Python-based framework that provides AI agents with read-search capabilities across web platforms. For Twitter (now X) integration, the library implements a flexible authentication system that leverages your existing browser session cookies rather than requiring manual OAuth flows. This guide covers the complete setup process using cookie-based authentication, including the specific configuration keys, backend detection logic, and secure credential storage mechanisms implemented in the codebase.

Authentication Backends and Discovery

Agent Reach supports three distinct backends for Twitter access, as implemented in agent_reach/channels/twitter.py (lines 14-34). The TwitterChannel.check() method automatically probes each backend to determine availability:

• twitter-cli: Probes the binary by running twitter status and inspecting output
• OpenCLI: Detects via self._check_opencli() which verifies server readiness through opencli_status
• bird (legacy): Calls bird check (or birdx) and examines the result

When a backend reports an ok status, Agent Reach marks it as active and routes all subsequent read() and search() calls through that implementation.

Where Credentials Are Stored

The authentication system centralizes credential management across three locations, defined in agent_reach/config.py and agent_reach/cookie_extract.py:

Configuration File

The primary storage is ~/.agent-reach/config.yaml. The specific keys used by Twitter backends are:

• twitter_auth_token
• twitter_ct0

Environment Variables

The Config.get() method implements fallback logic to uppercase environment variables. You can export:

• TWITTER_AUTH_TOKEN
• TWITTER_CT0

Browser Cookie Extraction

The agent_reach/cookie_extract.py module provides configure_from_browser(), which extracts auth_token and ct0 from local browsers (Chrome, Firefox, Edge, Brave, Opera) using rookiepy or browser-cookie3 libraries. This function also synchronizes credentials to legacy locations for compatibility: ~/.config/xfetch/session.json (for twitter-cli) and ~/.config/bird/credentials.env (for the bird CLI).

The Authentication Flow

The complete flow from browser extraction to active session involves four specific steps:

1. CLI Invocation: The configure command in agent_reach/cli.py (lines 1070-1085) parses --from-browser flags and invokes cookie_extract.configure_from_browser()
2. Cookie Extraction: The extractor reads the browser's SQLite cookie store and returns a structured dict: {"twitter": {"auth_token": "AAA", "ct0": "BBB"}}
3. Config Persistence: Values are written to config.yaml under the twitter_auth_token and twitter_ct0 keys
4. Backend Validation: When users run Twitter operations, TwitterChannel.check() verifies that config.get("twitter_auth_token") returns a value, marking the backend as ok

If credentials are missing, the channel reports a warn status and displays a hint to export the environment variables.

Configuration Methods

Auto-Configure from Browser (Recommended)

Run the CLI command to extract cookies from Chrome and automatically populate the configuration:

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

This executes cookie_extract.configure_from_browser('chrome', config), which extracts the tokens, writes them to ~/.agent-reach/config.yaml, and syncs to legacy locations.

Manual Environment Variable Setup

For CI/CD pipelines or temporary access, set the variables explicitly:

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

# Verify authentication status

python -m agent_reach.cli doctor

The doctor command invokes TwitterChannel.check(), which detects the environment variables and reports the backend as ok.

Programmatic Configuration

Access Twitter functionality directly from Python code using the AgentReach class:

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

# Load configuration from ~/.agent-reach/config.yaml

cfg = Config()
ar = AgentReach(config=cfg)

# Search Twitter content

results = ar.search("site:x.com \"machine learning\"")
print(results)

# Read specific tweet

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

The AgentReach instance routes requests to TwitterChannel.read() or TwitterChannel.search(), which delegate to the active backend (twitter-cli, OpenCLI, or bird).

Verify Stored Configuration

Inspect your configuration without exposing full secrets using the masking feature:

from agent_reach.config import Config

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

The to_dict() method (lines 108-130 in config.py) automatically masks any keys containing "auth", "token", or "ct0", preventing accidental credential leakage in logs.

Key Implementation Files

Understanding these source files helps when debugging authentication issues:

File	Responsibility
agent_reach/channels/twitter.py	Implements channel logic, backend probing, and credential validation
agent_reach/cookie_extract.py	Browser cookie extraction and legacy file synchronization
agent_reach/config.py	YAML storage, environment variable fallback, and secret masking
agent_reach/cli.py	Command-line interface for configure and doctor commands
agent_reach/core.py	Public AgentReach API that routes calls to appropriate channels
agent_reach/backends/opencli.py	OpenCLI server detection and status checking

Summary

• Cookie-based authentication for Twitter requires extracting auth_token and ct0 values from your browser session
• Storage options include ~/.agent-reach/config.yaml file or TWITTER_AUTH_TOKEN/TWITTER_CT0 environment variables
• CLI setup uses python -m agent_reach.cli configure --from-browser chrome to automate extraction
• Backend discovery happens automatically in agent_reach/channels/twitter.py through the check() method
• Security features include automatic masking of secrets when displaying configuration via cfg.to_dict()

Frequently Asked Questions

What specific cookie names does Agent Reach require for Twitter authentication?

Agent Reach specifically looks for the auth_token and ct0 cookies from your Twitter/X browser session. These are extracted automatically when using the --from-browser flag or can be set manually via the TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables.

Can I use Agent Reach with Twitter if I don't want to use browser cookie extraction?

Yes. You can manually export TWITTER_AUTH_TOKEN and TWITTER_CT0 as environment variables, or directly edit ~/.agent-reach/config.yaml to include the twitter_auth_token and twitter_ct0 keys. The Config.get() method in agent_reach/config.py checks environment variables before falling back to the config file.

Which browsers are supported for automatic cookie extraction?

The configure_from_browser() function in agent_reach/cookie_extract.py supports Chrome, Firefox, Edge, Brave, and Opera. The implementation uses rookiepy or browser-cookie3 libraries to read the browsers' SQLite cookie stores directly from your user profile directories.

What happens if my Twitter authentication expires or fails?

If credentials are invalid or expired, TwitterChannel.check() in agent_reach/channels/twitter.py will report a warn status instead of ok. The system prints a diagnostic message suggesting you run the configure command or export the environment variables. You can verify the current state anytime by running python -m agent_reach.cli doctor, which checks all configured channels and reports their authentication status.

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