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

> Learn how to set up cookie-based authentication for Twitter with Agent Reach. Extract and store auth cookies or use environment variables for AI agent access.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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:

```bash
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:

```python
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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) | Implements channel logic, backend probing, and credential validation |
| [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) | Browser cookie extraction and legacy file synchronization |
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) | YAML storage, environment variable fallback, and secret masking |
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Command-line interface for `configure` and `doctor` commands |
| [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) | Public `AgentReach` API that routes calls to appropriate channels |
| [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.