Features

• Multi-Account Management: Seamlessly manage and automate actions for multiple Twitter accounts.
• Content Scraping:
  • Scrape tweets based on keywords, user profiles, and news/research sites.
  • Extract tweet content, user information, and engagement metrics.
• Content Publishing:
  • Post new tweets, including text and media.
  • Reply to tweets based on various triggers.
  • Repost (retweet) content from competitor profiles or based on engagement metrics.
• LLM Integration:
  • Utilize OpenAI (GPT models) and Google Gemini for:
    • Generating tweet content and replies.
    • Analyzing tweet threads and sentiment.
    • Summarizing articles for posting.
  • Flexible LLM preference settings at global and per-account levels.
• Engagement Automation:
  • Engage with tweets through likes, replies, and reposts.
  • Analyze competitor activity and engage strategically.
• Configurable Automation:
  • Fine-grained control over automation parameters via JSON configuration files.
  • Per-account overrides for keywords, target profiles, LLM settings, and action behaviors.
• Browser Automation: Uses Selenium for interacting with Twitter, handling dynamic content and complex UI elements.
• Modular Design: Easily extendable with new features and functionalities.
• Logging: Comprehensive logging for monitoring and debugging.
• Community Posting: Switch audience and post into configured communities (by ID or name).
• Stealth Mode (Chrome): Optional undetected-chromedriver + selenium-stealth to reduce fingerprinting.
• Proxies: Per-account proxies, named proxy pools, and rotation strategies (hash/round-robin) with env interpolation.
• LLM Structured Prompts: Strict JSON prompting with few-shots, system prompts, and robust extraction.
• Metrics: Per-account JSON summaries and JSONL event logs for observability.

Technology Stack

• Programming Language: Python 3.9+
• Browser Automation: Selenium, WebDriver Manager
• HTTP Requests: Requests
• Data Validation: Pydantic
• LLM Integration: Langchain (for Google GenAI), OpenAI SDK
• Stealth: undetected-chromedriver, selenium-stealth (optional)
• Configuration: JSON, python-dotenv
• Web Interaction: Fake Headers (for mimicking browser headers)

Project Structure

The project is organized as follows:

twitter-automation-ai/
├── config/
│   ├── accounts.json       # Configuration for multiple Twitter accounts
│   └── settings.json       # Global settings (API keys, automation parameters)
├── src/
│   ├── core/               # Core modules (browser, LLM, config)
│   │   ├── browser_manager.py
│   │   ├── config_loader.py
│   │   └── llm_service.py
│   ├── features/           # Modules for Twitter features (scraper, publisher, etc.)
│   │   ├── scraper.py
│   │   ├── publisher.py
│   │   └── engagement.py
│   ├── utils/              # Utility modules (logger, file handler, etc.)
│   │   ├── logger.py
│   │   ├── file_handler.py
│   │   ├── progress.py
│   │   └── scroller.py
│   ├── data_models.py      # Pydantic models for data structures
│   ├── main.py             # Main orchestrator script
│   └── __init__.py
├── .env                    # Environment variables (optional, for API keys)
├── requirements.txt        # Python dependencies
├── .gitignore              # Specifies intentionally untracked files
├── LICENSE                 # Project license
├── CODE_OF_CONDUCT.md      # Contributor Code of Conduct
├── CONTRIBUTING.md         # Guidelines for contributing
└── README.md               # This file

Prerequisites

• Python 3.9 or higher.
• A modern web browser (e.g., Chrome, Firefox) compatible with Selenium.

Recommended Proxy Providers

Twitter's per-IP detection kills automation at scale. Use a quality proxy provider to keep your multi-account setup running reliably. The providers below are tested and recommended.

⭐ ScrapingAnt — Featured Provider

Private residential network with premium grade IPs — not resold traffic. Supports sticky sessions required for Twitter's IP consistency checks.

RapidProxy

RapidProxy

Dynamic and static residential proxies with free testing and unlimited, non-expiring traffic.

Setup and Configuration

Follow these steps to set up and run the project:

Presets (Beginner-Friendly)

Quick-start templates are available in presets/.

• Settings presets: presets/settings/*.json (defaults, Chrome undetected, proxies hash/round-robin)
• Accounts presets: presets/accounts/*.json (growth, brand_safe, replies_first, engagement_light, community_posting)
• How to apply:
  • cp presets/settings/beginner-chrome-undetected.json config/settings.json
  • cp presets/accounts/growth.json config/accounts.json
  • Edit placeholders for API keys, cookie paths, and community IDs.
  • See presets/README.md and data/README.md (dummy cookies/proxies).

1. Clone Repository

git clone https://github.com/ihuzaifashoukat/twitter-automation-ai
cd twitter-automation-ai

2. Create Virtual Environment

It's highly recommended to use a virtual environment:

python -m venv venv
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

3. Install Dependencies

Install the required Python packages:

pip install -r requirements.txt

4. Configure Accounts (config/accounts.json)

This file manages individual Twitter account configurations. It should be an array of account objects.

• Key Fields per Account:

  • account_id: A unique identifier for the account.
  • is_active: Boolean, set to true to enable automation for this account.
  • cookie_file_path: Path to a JSON file containing cookies for the account (e.g., config/my_account_cookies.json).
  • cookies: Alternatively, an array of cookie objects can be provided directly.
  • proxy (optional): Per-account proxy URL. Examples: http://user:pass@host:port, socks5://host:port.
  • post_to_community (optional): When true, switch the audience to a community before posting.
  • community_id (optional): Community ID used to select the audience (preferred).
  • community_name (optional): Fallback visible name in the audience picker if ID selection fails.
  • Overrides: You can specify per-account overrides for various settings like target_keywords_override, competitor_profiles_override, llm_settings_override, and action_config_override. If an override is not present, the global defaults from config/settings.json will be used.

• Example config/accounts.json entry:

  // Minimal example: ONLY add the community fields you need; keep your existing structure as-is.
  // Below shows adding community + (optional) proxy to one of your existing account objects:
  {
    "account_id": "your_existing_account_id",
    "is_active": true,
    "cookie_file_path": "config/your_existing_cookie_file.json",
    // ... all your existing fields remain unchanged ...
    "proxy": "http://127.0.0.1:8888",            // optional
    "post_to_community": true,                    // optional
    "community_id": "1737236915810627584",      // preferred when known
    "community_name": "One Piece"                // fallback by visible name
  }
  

  (Refer to the example in the original README section for a more detailed structure if needed, or adapt based on current data_models.py.)

• Obtaining Cookies: Use browser developer tools (e.g., "EditThisCookie" extension) to export cookies for x.com after logging in. Save them as a JSON array of cookie objects if using cookie_file_path.

• Per-Account Proxy: If set, the proxy overrides the global browser_settings.proxy for that account. Chrome uses --proxy-server; Firefox is configured via profile preferences (proxy auth prompts are not handled automatically).

• Community Posting: When post_to_community is true, the publisher clicks the "Choose audience" button in the composer and selects your community using community_id (preferred) or community_name as a fallback, then posts.

• Important: We do not require changing your existing accounts.json structure. Simply add the optional fields (post_to_community, community_id, community_name, and/or proxy) to the appropriate account objects.

• For rewrite-based posting to communities or personal profiles, ensure e