Thought Leader Agent System

24/7 LLM-powered autonomous agent for X/Twitter thought leadership growth. Runs headless with Puppeteer, generates content with LLMs, and behaves like a real human.

Overview

The agent system is a fully autonomous growth engine that:

• Browses X.com like a real user (feed, explore, search, profiles)
• Engages authentically — likes, comments, follows, reposts with LLM-generated human-like responses
• Creates original content — tweets, threads, and polls based on your persona and niche
• Avoids detection — randomized timing, human typing patterns, fingerprint rotation, circadian scheduling
• Tracks everything — SQLite database logs all actions, metrics, LLM usage, and costs
• Schedules intelligently — respects sleep hours, varies activity levels, uses gaussian randomness

Architecture

┌─────────────────────────────────────────────────────┐
│              ThoughtLeaderAgent (orchestrator)        │
│                                                       │
│  ┌─────────────┐  ┌──────────┐  ┌─────────────────┐ │
│  │ BrowserDriver│  │ LLMBrain │  │   Scheduler     │ │
│  │  (Puppeteer) │  │(OpenRouter│  │ (circadian +    │ │
│  │  + stealth)  │  │  /OpenAI) │  │  gaussian)      │ │
│  └──────┬───────┘  └────┬─────┘  └────────┬────────┘ │
│         │               │                  │          │
│  ┌──────┴───────┐  ┌────┴─────┐  ┌────────┴────────┐ │
│  │AntiDetection │  │ Persona  │  │ AgentDatabase   │ │
│  │(fingerprints,│  │(voice,   │  │ (SQLite, logs,  │ │
│  │ mouse, typing│  │ niche,   │  │  metrics)       │ │
│  │  simulation) │  │ style)   │  │                 │ │
│  └──────────────┘  └──────────┘  └─────────────────┘ │
│                                                       │
│  ┌───────────────┐  ┌──────────────────────────────┐ │
│  │ContentCalendar│  │   EngagementNetwork          │ │
│  │(weekly plans, │  │   (multi-agent coordination, │ │
│  │ auto-publish) │  │    ethics guardrails)        │ │
│  └───────────────┘  └──────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

Quick Start

1. Run the Setup Wizard

npx xactions agent setup
# or
npm run agent:setup

The wizard walks you through:

• Choosing a niche (AI Engineering, SaaS, Web3, or custom)
• Configuring your persona (name, tone, expertise, opinions)
• Setting up your LLM provider (OpenRouter recommended)
• Defining daily limits and schedule
• Browser settings (headless, proxy)

2. Log In to X.com

npx xactions agent login
# or
npm run agent:login

This opens a headed browser — log in manually, then press Enter. Your session cookies are saved to data/session.json.

3. Test for 5 Minutes

npx xactions agent test
# or
npm run agent:test

Runs the agent for 5 minutes so you can verify behavior before going 24/7.

4. Start the Agent

npx xactions agent start
# or
npm run agent

The agent runs continuously, sleeping during configured hours and varying activity intensity throughout the day.

5. Check Status & Reports

# Today's metrics
npx xactions agent status

# Last 7 days growth report
npx xactions agent report

# Last 30 days
npx xactions agent report --days 30

Configuration

The agent reads from data/agent-config.json. Copy the example to get started:

cp config/agent-config.example.json data/agent-config.json

Full Config Reference

{
  "niche": {
    "name": "AI Engineering",
    "searchTerms": ["AI agents", "LLM engineering", "developer tools"],
    "influencers": ["karpathy", "AndrewYNg", "ylecun"],
    "keywords": ["AI", "LLM", "GPT", "Claude", "machine learning"]
  },

  "persona": {
    "name": "Alex",
    "handle": "@alexbuilds",
    "niche": "AI & developer tools",
    "tone": "curious, technical but accessible, witty",
    "expertise": ["LLM engineering", "devtools", "AI agents"],
    "opinions": [
      "Open source wins long-term",
      "Ship fast, iterate faster"
    ],
    "avoid": [
      "corporate jargon", "hashtag spam", "engagement bait"
    ],
    "exampleTweets": [
      "Just spent 3 hours debugging a prompt that was missing one word."
    ],
    "replyStyles": {
      "question": 20,
      "agreement": 25,
      "insight": 35,
      "humor": 15,
      "pushback": 5
    }
  },

  "llm": {
    "provider": "openrouter",
    "apiKey": "",
    "models": {
      "fast": "deepseek/deepseek-chat",
      "mid": "anthropic/claude-3.5-haiku",
      "smart": "anthropic/claude-sonnet-4"
    }
  },

  "schedule": {
    "timezone": "America/New_York",
    "sleepHours": [23, 6]
  },

  "limits": {
    "dailyLikes": 150,
    "dailyFollows": 80,
    "dailyComments": 25,
    "dailyPosts": 5
  },

  "browser": {
    "headless": true,
    "sessionPath": "data/session.json"
  }
}

Config Fields

Niche Presets

Pre-built configs in config/niches/:

Persona Presets

Pre-built personas in config/personas/:

Components

ThoughtLeaderAgent

File: src/agents/thoughtLeaderAgent.js

The main orchestrator that runs the continuous activity loop. Each cycle:

1. Scheduler picks a weighted random activity
2. Agent executes the activity (browse feed, search, engage, create content)
3. Database logs the action
4. Scheduler calculates the next delay (with gaussian randomness)

Activity Types:

BrowserDriver

File: src/agents/browserDriver.js

Puppeteer wrapper with stealth plugins and session management.

Key methods:

• launch() / close() — Browser lifecycle
• navigate(url) — Navigate with random delays
• saveSession() / restoreSession() — Cookie persistence
• extractTweets() — Parse tweets from current page
• extractUsers() — Parse user cards from current page
• likeTweet(tweetEl) / followUser(userEl) / replyToTweet(tweetEl, text) — Engagement actions
• composeTweet(text) — Post a new tweet
• scrollDown() — Human-like scrolling

LLMBrain

File: src/agents/llmBrain.js

Tiered LLM integration with automatic retry and cost tracking.

Model tiers:

Key methods:

• scoreRelevance(tweet, persona) → number (0–100)
• generateReply(tweet, persona, style) → string
• generateContent(type, persona, topic) → { text } or string[] for threads
• checkPersonaConsistency(text, persona) → { consistent, issues }
• analyzeWeeklyPerformance(metrics) → string (strategic analysis)

Scheduler

File: src/agents/scheduler.js

Human-like activity scheduling with circadian rhythm simulation.

• 24-hour intensity curve (peak at 10am–2pm, minimum at 3am–5am)
• Gaussian random variance on all delays
• Sleep-hour enforcement (agent pauses entirely)
• Weighted random activity selection

AgentDatabase

File: src/agents/database.js

SQLite storage via better-sqlite3 with 5 tables:

Key methods:

• logAction(type, target, metadata) — Log any action
• getTodaySummary() — Today's action counts
• getGrowthReport(days) — Multi-day growth report
• getLLMCostReport(days) — LLM spend breakdown

AntiDetection

File: src/agents/antiDetection.js

Makes the agent behave like a real human:

• Mouse movement: Bezier curve simulation with natural acceleration
• Typing: Variable speed with occasional typos and corrections
• Fingerprints: 20+ real Chrome user-agent strings, randomized viewport, timezone, language
• Delays: Random pauses between actions that follow human patterns

Persona

File: src/agents/persona.js

Manages the agent's identity and voice consistency.

• getContext() — Returns persona summary for LLM system prompts
• validateContent(text) — Checks text against persona rules (avoid list)
• getRandomCommentStyle() — Weighted random reply style selection

ContentCalendar

File: src/agents/contentCalendar.js

Manages weekly content planning and publishing.

• generateWeeklyPlan(themes) — Creates a week of content slots
• getNextPost() — Returns the next scheduled post
• markPublished(postId, tweetId) — Records publication
• recordPerformance(tweetId, metrics) — Tracks post performance
• getStats() — Calendar statistics

EngagementNetwork

File: src/agents/engagementNetwork.js

Multi-agent coordination with ethical guardrails (optional).

• registerAgent(id, config) — Add an agent to the network
• shareDiscovery(agentId, discovery) — Share high-value content across agents
• shareTrend(agentId, trend) — Share trending topics
• checkEthics(from, to, type) — Validate interactions against ethics policy
• getNetworkStats() — Network health metrics

Ethics defaults: Self-retweet coordination disabled, coordinated liking disabled, human review required.

CLI Commands

# Full command reference
xactions agent --help

# Individual commands
xactions agent start [--config <path>]    # Start 24/7 agent
xactions agent test [--config <path>]     # 5-minute test run
xactions agent login                       # Browser login for auth
xactions agent setup                       # Interactive configuration wizard
xactions agent status [--config <path>]   # Today's metrics
xactions agent report [--days <n>]        # Growth report

Environment Variables

Data Files

All agent data is stored in the data/ directory:

Safety & Rate Limits

The agent is designed to stay within X's rate limits:

• Default limits: 150 likes, 80 follows, 25 comments, 5 posts per day
• 1–3 second delays between all actions
• Circadian rhythm reduces activity during off-hours
• Sleep hours pause all activity
• Anti-detection measures prevent automated behavior flags

Important: Automated action on X.com may lead to account restrictions. Start with conservative limits and increase gradually. Always use a test account first.

Testing

# Run all agent tests
npx vitest run tests/agents/

# Run specific module test
npx vitest run tests/agents/browserDriver.test.js

Test files: database, llmBrain, persona, scheduler, browserDriver, thoughtLeaderAgent, antiDetection, contentCalendar, engagementNetwork (120 tests total).