xBot/CLAUDE.md

xBot

AI-powered Twitter/X bot that generates tweets via the Anthropic Claude API and posts them using stealth browser automation through Kernel.sh (residential proxies + CAPTCHA solving).

Key Features

• AI tweet generation (claude-sonnet-4-6, max 280 tokens)
• Multi-account support (credentials keyed by account name in .env)
• Configurable scheduling (daily or random interval posting)
• Tweet history tracking to avoid repetition
• Link injection (URLs added post-generation, never sent to AI)
• Anti-detection: keyboard.type() with delays, adaptive login flow

Tech Stack

Node.js 18+ (ES modules), @onkernel/sdk, dotenv

Project Structure

• bot.js — Core logic: login to X, generate tweet via Claude, post it
• scheduler.js — Picks random times within a window, invokes bot.js via child_process
• cron.js — Docker entrypoint: writes prompts.json from env, fires scheduler.js daily at 4pm UTC
• Dockerfile — Node 18 alpine image
• package.json — Dependencies & scripts
• prompts.json — Prompt configs with account mapping, schedule, and link placeholders (not tracked)
• infra/docker-compose.yml — One service per prompt, named volume for history files
• infra/deploy-stack.sh — Deploys stack to Portainer (run once, or on compose changes)
• infra/.env — All secrets + PROMPTS_JSON (not tracked)
• infra/.env.example — Template

Entry Points

• node bot.js <prompt-name> — Post a single tweet immediately (local dev)
• node scheduler.js <prompt-name> — Schedule random posts for the day (local dev)
• node cron.js — Docker entrypoint (production)

External Services

Service	Purpose	Config Key
Kernel.sh	Stealth browser automation (residential proxies, CAPTCHA solving, Playwright)	KERNEL env var
Anthropic Claude API	Tweet generation	ANTHROPIC env var
X/Twitter	Target platform for posting	Per-account: {PREFIX}_USER, {PREFIX}_PW, {PREFIX}_EMAIL, {PREFIX}_PHONE

Multi-account credentials use uppercase prefix pattern in .env (e.g., MYACCOUNT_USER, MYACCOUNT_PW).

Deployment

Deployed on docker-server (Portainer):

• Portainer: https://portainer-1.docker.pq.io
• Registry: registry.docker.pq.io
• Stack: xbot
• Containers: xbot-<account>-<prompt> (e.g. xbot-thejunipersky-tease)
• Scheduling: cron.js fires at 4pm UTC daily — no host cron needed

To redeploy after code changes

1. Boot a t3.micro x86 build machine in AWS us-west-2 (key: twitter-bot-key, SG: sg-088158905150b9051, subnet: subnet-08fe6b8d1dc82f243)
2. Build and push: docker build --platform linux/amd64 -t registry.docker.pq.io/xbot:latest . && docker push registry.docker.pq.io/xbot:latest
3. Watchtower auto-restarts containers within 30s
4. Terminate build machine

To redeploy after compose/config changes

Run infra/deploy-stack.sh with PORTAINER_URL and PORTAINER_API_KEY set.

Guidelines

• All changes must preserve stealth/anti-detection behavior and multi-account architecture
• bot.js is the core; scheduler.js orchestrates timing
• Config lives in .env + prompts.json
• All project memory/context stays in this file (or a CLAUDE-memory/ folder in the repo) — never save to the external ~/.claude/projects/.../memory/ system