How to Configure Twitter/X Cookies Manually in Agent Reach

You can manually configure Twitter/X authentication in Agent Reach by running agent-reach configure twitter-cookies with either separate token values or a full cookie header string, which writes twitter_auth_token and twitter_ct0 to ~/.agent-reach/config.yaml.

Agent Reach stores authentication state for Twitter/X operations in a local YAML configuration file. When automatic browser extraction fails or is unavailable, you can manually supply the required auth_token and ct0 values through the command-line interface. This guide explains exactly how the manual cookie configuration flow works based on the source code implementation in the Panniantong/Agent-Reach repository.

Where Cookie Configuration Is Handled

The manual cookie configuration spans four key modules in the codebase. Understanding these components helps troubleshoot authentication issues and verify that tokens are stored securely.

CLI Command Parsing

In agent_reach/cli.py (lines 63–71), the _cmd_configure method handles the twitter-cookies subcommand. This branch accepts user input in two distinct formats: two separate arguments representing AUTH_TOKEN and CT0, or a single quoted string containing the full cookie header.

Cookie Parsing Logic

The helper function _parse_twitter_cookie_input in agent_reach/cli.py (lines 45–63) implements the parsing strategy. It detects the presence of = characters to determine if the input is a raw header string. If found, it extracts values using pattern matching for auth_token and ct0 keys. If absent, it splits the input on whitespace and treats the first element as auth_token and the second as ct0.

Secure Configuration Storage

The Config.set method in agent_reach/config.py (lines 80–84) persists the extracted values. It writes the keys twitter_auth_token and twitter_ct0 to ~/.agent-reach/config.yaml with file mode 0600, ensuring only the file owner can read or write these sensitive credentials.

Runtime Authentication

During Twitter channel checks, agent_reach/channels/twitter.py (lines 20–30) retrieves these values. The check method loads the configuration and exports the tokens as environment variables TWITTER_AUTH_TOKEN and TWITTER_CT0 before spawning the external twitter binary to verify connectivity.

Manual Configuration Methods

Agent Reach supports two input formats for manual cookie entry, accommodating different workflows for copying tokens from browser developer tools.

Using Separate Token Values

Pass the two tokens as distinct command arguments. This method works best when copying values individually from browser storage inspectors.

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

For example:

agent-reach configure twitter-cookies 123abc456def 789ghi012jkl

The parser detects no = characters in the input string, splits on whitespace, and assigns the first token to auth_token and the second to ct0.

Using a Full Cookie Header String

Supply the entire cookie header value as a single quoted argument. This method preserves exact formatting when copying directly from browser network tabs.

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

The _parse_twitter_cookie_input function identifies the auth_token= and ct0= patterns, extracts the associated values, and discards unrelated cookie attributes. Only the two required tokens are written to the configuration file.

Verifying the Configuration

After setting the cookies, validate the configuration using the built-in diagnostic command:

agent-reach doctor

Alternatively, re-run the configuration command with the same values to trigger the verification check. The CLI spawns twitter status with the environment variables populated from your config. If the external tool returns ok: true, the authentication is valid and the manual configuration succeeded.

Programmatic Access to Stored Cookies

If you need to access these tokens within custom scripts or plugins, use the Config class directly:

from agent_reach.config import Config

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

# Use in external API calls or custom integrations

print(f"Auth token: {auth_token}")
print(f"CT0 token: {ct0_token}")

This returns the same values written by the CLI command, allowing your code to remain synchronized with the Agent Reach configuration state.

Why Manual Configuration Is Required

While Agent Reach includes automatic extraction capabilities in agent_reach/cookie_extract.py (lines 44–53) via the configure_from_browser function, manual configuration becomes necessary in several scenarios. Headless servers and CI/CD pipelines lack graphical browsers for automatic extraction. Security-conscious environments may prohibit browser cookie access libraries like rookiepy or browser-cookie3. Additionally, manual entry provides precise control over which session tokens are active, avoiding conflicts when multiple Twitter accounts are logged into the same browser profile.

Summary

• Manual cookie configuration in Agent Reach uses the CLI command agent-reach configure twitter-cookies to write authentication tokens to ~/.agent-reach/config.yaml.
• Two input formats are supported: separate token arguments or a full cookie header string, parsed by _parse_twitter_cookie_input in agent_reach/cli.py.
• Secure storage is enforced through Config.set in agent_reach/config.py, which applies 0600 file permissions to protect credentials.
• Runtime usage occurs in agent_reach/channels/twitter.py, where tokens are exported as TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables for the external Twitter CLI tool.

Frequently Asked Questions

What file permissions does the configuration file use?

The Config.set method in agent_reach/config.py applies mode 0600 (owner read/write only) to ~/.agent-reach/config.yaml. This prevents other users on the system from accessing your Twitter authentication tokens, even if they have filesystem access to your home directory.

Can I extract cookies automatically instead of manual entry?

Yes. The agent_reach/cookie_extract.py module provides the configure_from_browser function (lines 44–53) which automatically extracts auth_token and ct0 from supported browsers. However, this requires Python packages like rookiepy or browser-cookie3 and a locally installed browser with an active Twitter session. Manual configuration serves as the fallback when automatic extraction is unavailable or fails.

How does Agent Reach pass cookies to the Twitter CLI?

The runtime check in agent_reach/channels/twitter.py (lines 20–30) loads the stored values and injects them as environment variables. Specifically, it sets TWITTER_AUTH_TOKEN to the value of twitter_auth_token and TWITTER_CT0 to the value of twitter_ct0 before executing the twitter status command to verify connectivity.

What happens if I provide malformed cookie input?

The _parse_twitter_cookie_input function in agent_reach/cli.py validates the input format. If the parser cannot identify both required tokens, the CLI displays an error message and exits without modifying the configuration file. This prevents corrupted credentials from overwriting valid existing tokens in ~/.agent-reach/config.yaml.

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