x-multi

AI-powered Twitter bot using VoltAgent, Google Gemini, and MCP Browser Server for automated tweet generation and posting.

Features

• AI-Generated Content: Uses Google Gemini to create engaging tweets based on topics
• Multi-Profile Support: Manage multiple Twitter accounts with isolated browser sessions
• Secure Manual Login: User logs in manually (no credential storage)
• Browser Automation: Leverages MCP Browser Server with Puppeteer for reliable automation
• Session Persistence: Browser profiles saved between runs - login once per account
• Visual Feedback: Browser window visible during operation
• Smart Automation: AI agent plans and executes browser interactions dynamically
• Custom Endpoints: Support for custom Gemini API endpoints (proxies, alternative deployments)

Architecture

This project combines three powerful technologies:

1. VoltAgent - TypeScript AI agent framework for orchestration
2. Google Gemini - LLM for tweet generation and automation planning
3. MCP Browser Server - Model Context Protocol server providing browser automation tools

See ARCHITECTURE.md for complete technical details.

Prerequisites

• Node.js 18 or newer
• Chrome or Edge browser installed
• Google Gemini API key from Google AI Studio
• Twitter/X account

Installation

1. Install dependencies:

npm install

2. Create .env file from the example:

cp .env.example .env

3. Edit .env and add your Google Gemini API key:

GOOGLE_API_KEY=your_gemini_api_key_here

Usage

Post a Tweet

Run the bot with a topic:

npm run tweet "Latest developments in AI"

What Happens

1. Browser Launch: Opens Chrome/Edge window and navigates to Twitter
2. Login Check: Verifies if you're already logged in
3. Manual Login (if needed):
   • Pauses and waits for you to login manually
   • Complete 2FA if required
   • Press Enter when done
4. Tweet Generation: AI creates engaging content about your topic
5. Automated Posting: Agent composes and posts the tweet
6. Verification: Takes screenshot and confirms success

Example

$ npm run tweet "Exciting breakthrough in quantum computing"

🚀 Initializing Twitter Bot...
✅ Agent initialized with Gemini model

🌐 Navigating to Twitter...
📊 Login Status: Not logged in

============================================================
⚠️  LOGIN REQUIRED
============================================================

👉 A browser window should be open with Twitter login page
📝 Please complete the login process manually:
   1. Enter your username/email
   2. Enter your password
   3. Complete 2FA if prompted
   4. Wait until you see your home timeline

✅ Press ENTER when you've successfully logged in...

[After manual login and pressing Enter]

🔄 Resuming automation...
🔍 Verifying login...
✅ Login verified successfully!

🤖 Generating tweet about: "Exciting breakthrough in quantum computing"...
📝 Generated tweet:
────────────────────────────────────────────────────────────
Major advancement in quantum computing: researchers achieve 99.9% qubit
stability, bringing us closer to practical quantum applications in
cryptography and drug discovery. The future is quantum! 🔬
────────────────────────────────────────────────────────────
📊 Length: 232/280 characters

📤 Posting tweet...
============================================================
✅ TWEET POSTED SUCCESSFULLY!
============================================================

Pre-authenticate Account (Optional)

For faster tweet posting, you can pre-login to your Twitter accounts. This saves the session and skips the login step on subsequent tweets.

Login to an Account

npm run login -- --profile <id>

Example:

# Pre-authenticate xrdavies account
npm run login -- --profile xrdavies

# Or use the default profile
npm run login

What happens:

1. Browser opens and navigates to Twitter
2. If not logged in, you'll be prompted to login manually
3. After login, the session is saved to the profile's browser directory
4. Future tweets with this profile will skip login (much faster!)

Benefits:

• ⚡ Faster tweet posting - No login delay when posting tweets
• 🔄 Session persistence - Login once, post many times
• 👥 Batch setup - Pre-authenticate all your accounts at once

Note: The npm run tweet command will automatically handle login if needed, so this step is optional but recommended for better performance.

Profile Management

x-multi supports multiple Twitter profiles, allowing you to manage and post from different accounts without manual switching.

Create a Profile

npm run profile:create -- <id> -h <@username> -p <platform> [-d "Description"] [-l <lang>] [-x "Proxy"]

Short-hand options:

• -h, --handle - Account handle (required)
• -p, --platform - Platform: twitter or bnsquare (required)
• -d, --description - Profile description (optional)
• -l, --language - Language for this account (optional)
• -x, --proxy - Proxy server (optional)

Example:

# Create Twitter profile
npm run profile:create -- personal -h @johndoe -p twitter -d "Personal account" -l en

# Create Binance Square profile
npm run profile:create -- mybns -h @myuser -p bnsquare -d "BNS account" -l zh

# Create with proxy
npm run profile:create -- business -h @mycompany -p twitter -l zh -x "socks5://proxy:8080"

Supported Languages:

• en - English
• zh - Chinese
• ja - Japanese
• ko - Korean
• es - Spanish
• pt - Portuguese

Proxy Support:

• Each profile can have its own proxy configuration
• Supported formats:
  • http://proxy:port or http://user:pass@proxy:port
  • https://proxy:port or https://user:pass@proxy:port
  • socks5://proxy:port or socks5://user:pass@proxy:port
  • socks4://proxy:port
• Optional: only add --proxy if you need to route traffic through a proxy
• Note: If your password contains special characters (:, @, etc.), URL-encode them

List All Profiles

npm run profile:list

Output:

📋 Available Profiles:

────────────────────────────────────────────────────────────────────────────────

🔹 personal [DEFAULT]
   Handle: @johndoe
   Platform: twitter
   Description: Personal account
   Language: en
   Created: 11/23/2025, 6:18:00 PM
   Last used: 11/23/2025, 6:30:15 PM
   Directory: <project-root>/browser-profiles/twitter-personal

🔹 mybns
   Handle: @myuser
   Platform: bnsquare
   Description: BNS account
   Language: zh
   Proxy: socks5://proxy:8080
   Created: 11/23/2025, 6:19:00 PM
   Never used
   Directory: <project-root>/browser-profiles/bnsquare-mybns

────────────────────────────────────────────────────────────────────────────────

Total: 2 profile(s)

Use a Specific Profile

npm run tweet "Your topic" -- --profile <id>

Examples:

# Post from personal account
npm run tweet "AI is fascinating" -- --profile personal

# Post from business account
npm run tweet "Product launch announcement" -- --profile business

Set Default Profile

npm run profile:default -- <id>

Example:

npm run profile:default -- business

After setting a default, tweets will use that profile unless you specify --profile:

# Uses default profile (business)
npm run tweet "Latest update"

# Override with specific profile
npm run tweet "Personal thought" -- --profile personal

Update a Profile

npm run profile:update -- <id> [options]

Options:

• -h, --handle <@username> - Update account handle
• -d, --description <text> - Update description
• -l, --language <lang> - Set language (en, zh, ja, ko, es, pt)
• -x, --proxy <proxy> - Set or update proxy server
• --no-proxy - Remove proxy configuration

Examples:

# Update language for a profile
npm run profile:update -- personal -l zh

# Add proxy to existing profile
npm run profile:update -- personal -x "socks5://proxy:8080"

# Update multiple fields
npm run profile:update -- business -d "Updated description" -l ja -x "http://newproxy:3128"

# Remove proxy from profile
npm run profile:update -- personal --no-proxy

Delete a Profile

npm run profile:delete -- <id>              # Delete profile config only
npm run profile:delete -- <id> --delete-data  # Also delete browser data

Example:

# Delete profile but keep browser session data
npm run profile:delete -- old-account

# Delete everything including cookies and login state
npm run profile:delete -- old-account --delete-data

How Profiles Work

• Each profile is associated with a specific platform (Twitter or Binance Square)
• Each profile has its own isolated browser session (cookies, login state, cache)
• Each profile has a language setting that determines the language for posts
• Each profile can have its own proxy configuration (optional)
• Browser profiles are stored in browser-profiles/{platform}-{id}/ directory
  • Example: browser-profiles/twitter-personal/, browser-profiles/bnsquare-mybns/
• Configuration is saved in config/profiles.json (safe to commit to git)
• Browser data is git ignored (kept private)
• Profiles remember login state between runs

First-Time Profile Setup

When you create a new profile, you'll need to login once. You have two options:

Option 1: Pre-authenticate with login command (recommended)

# Create profile
npm run profile:create -- work -h @workaccount -p twitter

# Pre-authenticate (faster for subsequent posts)
npm run login -- --profile work

# Browser opens, login manually, press Enter

# Now post without login delay
npm run tweet "Hello from work" -- --profile work  # Already logged in!
npm run tweet "Another tweet" -- --profile work    # Still logged in!

Option 2: Login on first post

# Create profile
npm run profile:create -- work -h @workaccount -p twitter

# First post with this profile (includes login)
npm run tweet "Hello from work" -- --profile work

# Browser opens, login manually, press Enter

# Future posts automatically use saved session
npm run tweet "Another tweet" -- --profile work  # No login needed!

Persona Management

x-multi supports multiple KOL personas, allowing different Twitter accounts to post with distinct voices and styles. Personas define HOW accounts tweet (tone, style, expertise), while profiles define WHO tweets and in WHICH language.

Architecture: Profile (WHO + WHICH language) → Persona (HOW to speak)

Pre-configured Personas

The system comes with 5 pre-configured personas:

• neutral - Neutral Web3 Commentator (balanced, semi-formal)
• web3-dev - Web3 Developer (technical, minimal emojis)
• crypto-trader - Crypto Trader (analytical, moderate emojis)
• bounty-hunter - Bounty Hunter (enthusiastic, frequent emojis)
• alpha-chaser - Alpha Chaser (excited, frequent emojis)

List All Personas

npm run persona:list

Show Persona Details

npm run persona:show <id>

Example:

npm run persona:show web3-dev

Create a New Persona

npm run persona:create -- --id <id> --name "<name>" --role <role> [options]

Roles:

• developer - Web3 developer, technical focus
• trader - Crypto trader, market/trading focus
• bounty_hunter - Bounty hunter, opportunity focus
• alpha_chaser - Alpha chaser, early opportunities
• general - General/neutral commentator

Options:

• --expertise <items> - Comma-separated expertise areas (default: web3,crypto,blockchain)
• --tone <tone> - Overall tone (default: balanced)
• --formality <level> - casual, semi-formal, formal (default: semi-formal)
• --emoji <usage> - none, minimal, moderate, frequent (default: moderate)
• --hashtags <preference> - none, low, medium, high (default: medium)

Example:

npm run persona:create -- --id my-persona --name "My Custom KOL" --role developer --tone technical --formality casual --emoji minimal

Link Profile to Persona

npm run persona:link <profileId> <personaId>

Example:

# Link xrdavies profile to web3-dev persona
npm run persona:link xrdavies web3-dev

# Link a Chinese-language profile to the same persona
npm run persona:link alice web3-dev
# Now alice will tweet in Chinese using web3-dev's technical style

View All Mappings

npm run persona:mappings

Output:

🔗 Profile-Persona Mappings:

────────────────────────────────────────────────────────────────────────────────

📱 xrdavies [DEFAULT] → 🎭 web3-dev
   Profile: @xrdavies
   Description: Account xrdavies
   Persona: Web3 Developer (developer)
   Language: en

────────────────────────────────────────────────────────────────────────────────

Total: 1 mapping(s)

Update a Persona

npm run persona:update <id> [options]

Options:

• --name <name> - Update display name
• --tone <tone> - Update tone
• --expertise <items> - Update expertise (comma-separated)

Example:

npm run persona:update web3-dev --tone "highly technical" --expertise "smart contracts,security,zk-proofs"

Delete a Persona

npm run persona:delete <id>

Unlink Profile from Persona

npm run persona:unlink <profileId> [personaId]

Examples:

# Unlink specific persona from profile
npm run persona:unlink xrdavies web3-dev

# Unlink all personas from profile
npm run persona:unlink xrdavies

Session Persistence

After your first manual login, the browser profile is saved in ./browser-profile/. On subsequent runs:

• You'll stay logged in automatically
• No need to enter credentials again
• Just run the command and tweet!

To force a fresh login:

rm -rf browser-profile/

Configuration

Environment Variables

# Required
GEMINI_API_KEY=your_gemini_api_key_here

# Optional
GEMINI_MODEL=gemini-2.5-pro     # AI model to use
HEADLESS=false                  # Run browser in headless mode

# Optional: Custom Gemini API endpoint (proxy or alternative deployment)
# GEMINI_BASE_URL=https://your-custom-endpoint.com/v1beta

Note: Browser profiles are managed through the profile system (see Profile Management section above). Each profile has its own isolated browser session stored in browser-profiles/<profile-id>/.

Available Models

• gemini-2.5-pro (default) - Latest and most capable model
• gemini-2.0-flash-exp - Fast experimental model
• gemini-1.5-pro - Previous generation, reliable
• gemini-1.5-flash - Previous generation, fast

Project Structure

/Users/r001/work/x-multi/
├── src/
│   ├── index.ts              # Main CLI application
│   ├── config/
│   │   ├── mcp.ts           # MCP server configuration
│   │   └── agent.ts          # VoltAgent setup
│   ├── prompts/
│   │   └── system.ts         # AI agent instructions
│   └── utils/
│       └── login.ts          # Manual login handler
├── browser-profile/          # Browser session (created at runtime)
├── .env                      # Your configuration
├── package.json
└── ARCHITECTURE.md           # Complete technical documentation

Troubleshooting

Browser doesn't open

• Ensure Chrome or Edge is installed
• Check that @agent-infra/mcp-server-browser installed correctly: npm install

Login verification fails

• Wait for Twitter home feed to fully load before pressing Enter
• Ensure "Post" button is visible in the browser
• Try refreshing the page if stuck

Tweet posting fails

• Verify tweet is under 280 characters
• Ensure you're on the home feed, not profile or other pages
• Check browser screenshots for error messages

API errors

• Verify GOOGLE_API_KEY is set correctly in .env
• Check API quota at Google AI Studio
• Ensure stable internet connection

Development

Build TypeScript

npm run build

Run in Development Mode

npm run dev "your topic here"

Type Check

npm run type-check

How It Works

1. VoltAgent Core orchestrates the entire workflow
2. Gemini AI generates tweet content and plans browser automation steps
3. MCP Browser Server provides 20+ browser automation tools via stdio
4. Agent intelligently calls browser tools to navigate, compose, and post
5. Screenshot verification ensures successful posting

Security

• No Credential Storage: You login manually each session
• Session Cookies: Stored locally in browser-profile/ (gitignored)
• API Key: Stored in .env file (gitignored)
• Manual Control: You control when tweets are posted

License

MIT

Resources

• VoltAgent Documentation
• Google Gemini API
• MCP Browser Server
• Complete Architecture Guide

Support

For issues or questions:

1. Check ARCHITECTURE.md for technical details
2. Review the troubleshooting section above
3. Check browser screenshots in the output for visual debugging