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

Agent Reach stores Twitter/X authentication tokens in ~/.agent-reach/config.yaml under the keys twitter_auth_token and twitter_ct0, which you can set manually via the agent-reach configure twitter-cookies CLI command when automatic browser extraction is unavailable.

Agent Reach is an open-source automation framework that integrates with Twitter/X through external CLI tools. When running in headless environments, CI pipelines, or systems without supported browsers, you must manually configure Twitter/X authentication cookies to enable channel monitoring and posting capabilities.

How Authentication Flows Through the Codebase

The credential flow spans four core modules according to the Panniantong/Agent-Reach source code:

• CLI Parsing: In agent_reach/cli.py (lines 63-71), the _cmd_configure function handles the twitter-cookies subcommand, accepting either separate tokens or a full cookie header.
• Input Processing: The _parse_twitter_cookie_input helper (lines 45-63) in the same file detects whether input contains = signs (header format) or whitespace (separate tokens).
• Secure Storage: The Config.set method in agent_reach/config.py (lines 80-84) persists values to ~/.agent-reach/config.yaml with file mode 0600 (owner-read/write only).
• Runtime Injection: The check method in agent_reach/channels/twitter.py (lines 20-30) exports these values as TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables when spawning the external twitter binary.

Manual Configuration Methods

Agent Reach supports two input formats for manual cookie configuration.

Method 1: Provide Two Separate Tokens

Pass the auth_token and ct0 values as separate arguments to the CLI:

agent-reach configure twitter-cookies <AUTH_TOKEN> <CT0>

For example:

agent-reach configure twitter-cookies 123abc456def 789ghi012jkl

The _parse_twitter_cookie_input function detects the absence of = signs and splits on whitespace, assigning the first value to twitter_auth_token and the second to twitter_ct0.

Method 2: Paste a Full Cookie Header String

Alternatively, paste the raw cookie header copied from your browser's developer tools:

agent-reach configure twitter-cookies "auth_token=123abc456def; ct0=789ghi012jkl; ..."

The parser extracts values for keys auth_token and ct0 from the semicolon-delimited string.

Resulting Configuration File

After execution, your ~/.agent-reach/config.yaml contains:

# ~/.agent-reach/config.yaml

twitter_auth_token: 123abc456def
twitter_ct0: 789ghi012jkl

The file is written with secure permissions (mode 0600) to prevent unauthorized access to these sensitive tokens.

Verifying the Configuration

Confirm your credentials are valid by running the diagnostic command:

agent-reach doctor

This invokes the check method in agent_reach/channels/twitter.py, which spawns the twitter binary with the environment variables set:

env["TWITTER_AUTH_TOKEN"] = auth_token
env["TWITTER_CT0"] = ct0

A green checkmark for "Twitter/X" indicates successful authentication. You can also re-run the configuration command to trigger the verification test explicitly.

Accessing Tokens Programmatically

If you need to read these values in custom Python code:

from agent_reach.config import Config

cfg = Config()
auth_token = cfg.get("twitter_auth_token")
ct0 = cfg.get("twitter_ct0")

These values match exactly what the CLI wrote to the YAML file.

When Manual Configuration Is Required

Automatic extraction via agent_reach/cookie_extract.py (lines 44-53) requires supported browsers and Python packages like rookiepy or browser-cookie3. Manual configuration becomes necessary when:

• Operating in headless VMs or Docker containers without browsers
• Running in CI/CD pipelines where browser installation is impractical
• Using custom environments where the automatic configure_from_browser function cannot locate cookie stores

Summary

• Storage Location: Twitter/X cookies reside in ~/.agent-reach/config.yaml as twitter_auth_token and twitter_ct0.
• CLI Command: Use agent-reach configure twitter-cookies with either two separate tokens or a full cookie header string.
• Security: The config file uses mode 0600 permissions to protect sensitive credentials.
• Runtime Usage: The application exports these values as TWITTER_AUTH_TOKEN and TWITTER_CT0 when calling the external twitter binary.
• Alternative: Automatic extraction is available via agent_reach/cookie_extract.py when browser environments are present.

Frequently Asked Questions

Where does Agent Reach store Twitter authentication tokens?

Agent Reach stores the tokens in a YAML configuration file located at ~/.agent-reach/config.yaml. The specific keys are twitter_auth_token and twitter_ct0, written with secure file permissions (mode 0600) to ensure only the file owner can read or modify them.

Can I use a raw browser cookie string instead of separate tokens?

Yes. The _parse_twitter_cookie_input function in agent_reach/cli.py accepts a full cookie header string (e.g., "auth_token=abc; ct0=xyz") and extracts the values automatically. This is useful when copying directly from browser developer tools.

How does Agent Reach use these cookies at runtime?

The check method in agent_reach/channels/twitter.py retrieves the stored values and exports them as environment variables TWITTER_AUTH_TOKEN and TWITTER_CT0 before spawning the external twitter binary. This allows the CLI tool to authenticate without storing credentials separately.

What if I want to automate cookie extraction instead of manual entry?

Agent Reach includes an automatic extraction module in agent_reach/cookie_extract.py (lines 44-53) via the configure_from_browser function. This reads cookies directly from supported browsers using libraries like rookiepy or browser-cookie3, but requires a local browser installation and is not suitable for headless environments.

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