🤖 Autonomous Twitter/X Agent - Full Stack Monorepo

A complete autonomous agent system for Twitter/X interactions using a decoupled architecture with MCP (Model Context Protocol), ElizaOS, and a React Dashboard.

📚 Documentation

• Architecture Overview - System design, components, and data flow
• API Reference - Complete REST API documentation
• Deployment Guide - Step-by-step production setup
• User Manual - Dashboard usage and workflows
• Production Deployment - Implementation details

🏗️ Architecture

Monorepo Structure:
├── packages/
│   ├── mcp-server/     # Twitter API integration layer
│   ├── eliza-agent/    # AI agent controller
│   └── ui/            # React dashboard for monitoring
├── data/postgres/     # Persistent database storage
├── scripts/           # Utility scripts (backup, etc.)
└── docker-compose*.yaml # Development and production orchestration

Full Stack Architecture:
┌─────────────────┐    REST API      ┌─────────────────┐
│   React UI      │◄────────────────►│ ElizaOS Agent   │
│   Dashboard     │                  │   (The Brain)   │
│   (The Face)    │                  │                 │
└─────────────────┘                  │ - Personality   │
          │                          │ - Decision      │
          │                          │ - API Server    │
          │                          └─────────────────┘
          │                                   │
          │                          MCP Protocol
          │                                   │
          │                          ┌─────────────────┐
          │                          │   MCP Server    │
          │                          │   (The Hands)   │
          └─────────────────────────►│                 │
                                     │ - Twitter API   │
                                     │ - Read/Write    │
                                     │ - Safety        │
                                     └─────────────────┘
                                              │
                                              │
                                              ▼
                                             Twitter/X

🚀 Quick Start

Prerequisites

• Node.js 22+
• pnpm (package manager)
• Rettiwt API key (for Twitter access)
• OpenAI API key (for AI reasoning)

1. Clone & Install

git clone <repository-url>
cd x-bot
pnpm install

2. Configure Environment

# Copy environment templates
cp packages/mcp-server/.env.example packages/mcp-server/.env
cp packages/eliza-agent/.env.example packages/eliza-agent/.env

# Edit .env files with your API keys:
# - RETTIWT_API_KEY
# - OPENAI_API_KEY

3. Build & Start

# Build all packages
pnpm build

# Development mode (starts both services)
pnpm dev

# Production deployment
pnpm deploy

📦 Package Structure

packages/mcp-server/

MCP Server - Twitter API integration layer

• ✅ 6 Twitter Operations: Search, profile lookup, timeline, posting, liking, retweeting
• ✅ Safety Features: Dry-run mode, rate limit handling, input validation
• ✅ Error Handling: Distinct error messages for ElizaOS decision-making

packages/eliza-agent/

ElizaOS Agent - AI controller and personality layer

• ✅ Twitter Curator Persona: Content analysis, sentiment monitoring, quality engagement
• ✅ MCP Integration: Stdio protocol connection to MCP server
• ✅ Process Management: PM2 configuration with auto-restart and logging

🛠️ Development Scripts

# Install all dependencies
pnpm install

# Build all packages
pnpm build

# Clean all builds
pnpm clean

# Development servers
pnpm dev:mcp      # Start MCP server only
pnpm dev:eliza    # Start Eliza agent only
pnpm dev          # Start both services

# Production
pnpm start        # Start Eliza agent (connects to MCP server)
pnpm deploy       # PM2 production deployment
pnpm logs         # View PM2 logs

⚙️ Configuration

Environment Variables

Create .env files in each package:

MCP Server (packages/mcp-server/.env):

RETTIWT_API_KEY=your_rettiwt_api_key_here
DRY_RUN=true  # Optional: Enable dry-run mode

Eliza Agent (packages/eliza-agent/.env):

OPENAI_API_KEY=your_openai_api_key_here
RETTIWT_API_KEY=your_rettiwt_api_key_here

Character Configuration

The bot's personality is defined in packages/eliza-agent/characters/rettiwt-bot.json:

• Bio & Lore: Personality and background
• Topics: Focus areas (AI, technology, social issues)
• Style: Communication guidelines
• MCP Servers: Connection configuration

🛡️ Safety Features

• 🧪 Dry Run Mode: DRY_RUN=true logs all actions without API calls
• 📏 Input Validation: 280-character limit enforcement
• ⏱️ Rate Limit Handling: Automatic detection with distinct error messages
• 🔄 Process Monitoring: PM2 auto-restart on failures
• 📝 Comprehensive Logging: File-based logging with rotation

🔧 Available Operations

Read Operations

• search_tweets - Search Twitter with keywords
• get_user_profile - Get user profile information
• get_user_timeline - Get user's recent tweets

Write Operations

• post_tweet - Post new tweets (with replies)
• like_tweet - Like tweets
• retweet - Retweet tweets

📊 Monitoring

# View PM2 process status
pm2 monit

# View logs
pm2 logs eliza-twitter-bot

# Restart services
pm2 restart eliza-twitter-bot

🚀 Deployment Options

PM2 (Recommended)

pnpm deploy

Docker Compose (Full Stack)

# Start all services: PostgreSQL database, ElizaOS agent, and React dashboard
docker compose up

# Access the dashboard
open http://localhost:5175

# Stop all services
docker compose down

Services:

• Database: PostgreSQL with pgvector on localhost:5434
• Agent API: ElizaOS agent on localhost:5566
• Dashboard: React UI on localhost:5175

Railway

One-click deployment via the included Railway configuration.

🔍 Troubleshooting

Common Issues

1. API Key Errors

   # Verify keys are set
   echo $RETTIWT_API_KEY
   echo $OPENAI_API_KEY

2. Connection Issues

   # Check MCP server is running
   ps aux | grep tsx

3. Rate Limits

   • The system automatically handles rate limits
   • Enable dry-run mode for testing: DRY_RUN=true

Debug Mode

DEBUG=* pnpm start --characters="packages/eliza-agent/characters/rettiwt-bot.json"

🤝 Contributing

1. Development: Use pnpm dev for simultaneous development
2. Testing: Enable DRY_RUN=true to test without API calls
3. Deployment: Test with PM2 before production deployment

📄 License

ISC License

---

Built with ❤️ using ElizaOS and MCP Protocol