llms-full.txt

# XActions

> ⚡ The Complete X/Twitter Automation Toolkit — Scrapers, MCP server for AI agents (Claude/GPT), CLI, browser scripts. No API fees. Open source. By nichxbt.

## Overview

XActions automates X/Twitter without needing official API access. It combines 60+ browser-paste scripts, Puppeteer-based scrapers, an MCP server for AI agent integration, a CLI tool, and a full-stack Express.js web dashboard backed by PostgreSQL.

## Architecture

Three runtime contexts:

1. **Browser scripts** — IIFE scripts pasted into DevTools console on x.com. Use DOM APIs and `sessionStorage`. No Node.js.
2. **Node.js library/CLI/MCP** — Runs locally or on a server. Uses Puppeteer for browser automation. Entry points: `src/cli/index.js`, `src/mcp/server.js`.
3. **API server** — Express.js backend at `api/server.js`. PostgreSQL via Prisma ORM, Bull + Redis job queue, Socket.io for realtime.

## Tech Stack

- **Runtime**: Node.js >= 18, ESM (`"type": "module"`)
- **Backend**: Express.js, Helmet, CORS, rate limiting, Morgan
- **Database**: PostgreSQL via Prisma ORM (`prisma/schema.prisma`)
- **Job Queue**: Bull + Redis
- **Browser Automation**: Puppeteer + puppeteer-extra-plugin-stealth
- **Testing**: Vitest 4.x (config: `vitest.config.js`)
- **MCP**: `@modelcontextprotocol/sdk`
- **Payments**: Stripe + x402 crypto
- **Realtime**: Socket.io

## Project Structure

```
src/                → Core library
  ├── cli/          → CLI commands (commander.js)
  ├── mcp/          → MCP server for AI agents
  ├── scrapers/     → Puppeteer scrapers (twitter/, bluesky/, mastodon/, threads/)
  ├── client/       → HTTP-only Twitter client (no Puppeteer)
  ├── automation/   → Browser automation scripts (require core.js first)
  ├── agents/       → Thought leader agent, persona engine
  ├── analytics/    → Engagement analytics
  ├── streaming/    → Real-time tweet streaming
  ├── plugins/      → Plugin system
  ├── ai/           → LLM integrations
  ├── a2a/          → Agent-to-Agent protocol
  ├── workflows/    → Multi-step automation
  ├── utils/        → Shared utilities
  └── *.js          → 60+ individual feature scripts
api/                → Express.js backend
  ├── server.js     → Main entry
  ├── routes/       → REST endpoints
  ├── services/     → Business logic, job queue, payments
  ├── middleware/    → Auth, rate limiting, error handling
  └── realtime/     → Socket.io handlers
dashboard/          → Static HTML frontend
skills/             → 32 Agent Skills (skills/*/SKILL.md)
tests/              → Vitest tests
types/              → TypeScript declarations (index.d.ts)
prisma/             → Database schema + migrations
docs/agents/        → DOM selectors, browser-script patterns, contributing guide
```

## Key Features

- **Scraping**: Profiles, followers, following lists, tweets, media, bookmarks, trending topics across Twitter, Bluesky, Mastodon, Threads
- **Unfollow Management**: Mass unfollow, unfollow non-followers, detect unfollowers
- **Growth Automation**: Auto-like, auto-follow, keyword follow, engagement automation
- **Content Posting**: Tweets, threads, polls, scheduling, reposts
- **Algorithm Cultivation**: Thought leader training, niche optimization, persona engine
- **Follower Monitoring**: Real-time alerts, continuous tracking, account snapshots
- **MCP Server**: Full integration with Claude Desktop and AI agents
- **A2A Protocol**: Agent-to-Agent communication
- **Analytics**: Engagement metrics, audience overlap, competitor intelligence
- **Community**: Join/leave communities, list management
- **Content Management**: Delete tweets, unlike, clear history, bookmark management
- **Direct Messages**: Auto DM, message management
- **Spaces**: Create, join, schedule Twitter Spaces
- **Profile Management**: Edit profile, avatar, header, bio
- **Browser Extension**: Chrome/Edge extension for in-browser automation

## Database Models (Prisma)

- `User` — Auth (Twitter OAuth + session cookies), credits, admin flags
- `Subscription` — Stripe billing (free/basic/pro/enterprise)
- `Operation` — Automation job tracking (type, status, progress, result)
- `JobQueue` — Bull job persistence
- `AccountSnapshot` / `FollowerSnapshot` / `FollowerChange` — Follower monitoring
- `Payment` / `CryptoPayment` — Stripe and x402 payments
- `License` — License management

## npm Package Exports

```
xactions           → ./src/index.js (main)
xactions/scrapers  → ./src/scrapers/index.js
xactions/streaming → ./src/streaming/index.js
xactions/analytics → ./src/analytics/index.js
xactions/plugins   → ./src/plugins/index.js
xactions/mcp       → ./src/mcp/server.js
xactions/cli       → ./src/cli/index.js
xactions/client    → ./src/client/index.js
```

## CLI Binaries

- `xactions` → CLI tool (`src/cli/index.js`)
- `xactions-mcp` → MCP server (`src/mcp/server.js`)
- `xactions-agent` → Thought leader agent (`src/agents/thoughtLeaderAgent.js`)

## Repository

- URL: https://github.com/nirholas/XActions
- Language: JavaScript (ESM)
- License: MIT
- Author: nirholas (@nichxbt)
- Node.js >= 18 required

## Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.