Autonomous Social Agent

𝕏-Bot

A Python-based autonomous Twitter/X bot that reads, reasons, generates, evaluates, and posts with scheduler automation, memory-backed deduplication, and live observability.

View Architecture Quick Start Full Presentation

Problem and Solution

The Problem

  • Manual posting is time-intensive and inconsistent.
  • Human-only workflows often miss engagement windows.
  • High-volume timeline scanning is hard to maintain.

The Solution

  • Autonomous posting with configurable personality.
  • Timeline reading plus LLM-based interest detection.
  • Inspiration queue for context-aware content generation.
  • Notification monitoring and processing queue.
  • Memory deduplication to avoid repeated content.

Architecture and Pipeline

🕒

Scheduler

APScheduler

⚙️

Jobs Layer

Posting • Reading • Notifications • Replies • Inspiration

𝕏

X Automation

Selenium + undetected-chromedriver + stealth

🧩

LangChain + LangGraph

Generation, validation, reading, and notifications workflows

🤖

LLM Providers

OpenRouter • OpenAI • Google • Anthropic

🧠

ChromaDB Memory

Embedding cache + duplicate detection (0.85)

💾

State Storage

JSON runtime state + SQLite analytics

🌐

FastAPI Dashboard

Jinja2 + HTMX + Chart.js + live settings reload

1

Read Timeline

Extract frontpage posts from X via Selenium.

2

Interest Check

Score relevance against configured personality topics.

3

Queue Signals

Store matching posts in the inspiration queue.

4

Generate Draft

Create inspired tweet candidates from queued context.

5

Quality Gate

Run re-evaluation and duplicate detection checks.

6

Post to X

Publish approved content and persist state/analytics.

Current Status

Roadmap-driven status summary.

Implemented

  • Scheduler and periodic jobs
  • Frontpage reading and interest detection
  • Inspiration-based posting flow
  • Notification checking and queueing
  • Memory deduplication via ChromaDB
  • FastAPI dashboard and token analytics

Partial

  • Notification pipeline is present, but reply automation is incomplete.
  • Roadmap has some legacy checkboxes not fully reflected in running behavior.

Planned / Missing

  • Positive intent detection for replies
  • Automated reply generation and posting
  • Trends integration and topic-aware enrichment

Roadmap

Near-term first, then post-MVP enhancements from ROADMAP.md.

Near-Term Priorities

  • Intent detection to filter toxic or low-quality interactions
  • Reply generation for positive notifications
  • Dashboard authentication and security hardening

Post-MVP Enhancements

  • Trends ingestion and compliance-aware topic handling
  • RSS and event ingestion pipelines
  • Cost tracking per LLM provider
  • Multi-account support

Reliability and Compliance

Rate Limits

Per-day post and reply caps with UTC reset logic to reduce risk and enforce operational boundaries.

Duplicate Prevention

Embedding-based similarity checks in ChromaDB (configured threshold 0.85) block repeated content.

Operational Controls

Structured logging, scheduler guardrails, and stateful queues keep automation observable and predictable.

Dashboard and Observability

FastAPI + Jinja2 + HTMX dashboard for live visibility and control.

Dashboard

Status, activity stats, rate-limit progress.

Posts

Read, written, rejected, and interested queues.

Analytics

Hourly token graph and provider usage breakdown.

Settings

Live YAML updates with runtime config reload support.

Logs

Real-time log view for operations and diagnostics.

Chat

Interactive generation workflow in the web interface.

Tech Stack

LayerTechnology
LanguagePython 3.13+
AI OrchestrationLangChain + LangGraph
LLM ProvidersOpenRouter, OpenAI, Google, Anthropic
Browser AutomationSelenium + undetected-chromedriver + selenium-stealth
SchedulerAPScheduler
MemoryChromaDB
State and AnalyticsJSON state + SQLite (aiosqlite)
WebFastAPI + Jinja2 + HTMX + Chart.js

Quick Start

Exact commands from README.md.

Requirements

  • Python 3.13+
  • uv
  • Google Chrome

Environment Variables

Set TWITTER_USERNAME, TWITTER_PASSWORD, and at least one LLM API key.

Setup

uv sync
cp config/env.template .env

Run Bot

uv run python main.py

Run Dashboard

uv run python -m src.web.app

Tests

uv run pytest

Dashboard URL: http://localhost:8000