x-monitor

🐦 X Monitor

An OpenClaw skill — Monitor X/Twitter accounts and topics with AI-enriched Discord alerts. Fully agentic, cron-powered, self-healing.

---

What It Does

X Monitor watches X/Twitter on your behalf and pushes rich Discord alerts in real time:

---

Prerequisites

---

Installation

# 1. Clone the repo
git clone https://github.com/your-username/x-monitor.git
cd x-monitor

# 2. Install dependencies
npm install

# 3. Run the setup wizard
npm run setup

The setup wizard will walk you through:

• Entering your X.com auth_token and ct0 cookies
• Entering your Discord bot token and channel IDs
• Creating data/ and logs/ directories
• (Optional) Verifying your X session
• (Optional) Installing OpenClaw cron jobs

---

Getting Your Credentials

X.com auth_token + ct0

1. Open x.com in Chrome and log in
2. Press F12 → Application tab → Cookies → https://x.com
3. Find auth_token and ct0 — copy their values

Discord Bot Token + Channel IDs

1. Go to discord.com/developers/applications
2. Create a new application → Bot tab → copy the token
3. Invite the bot to your server with Send Messages + Use Slash Commands permissions
4. Right-click any channel → Copy Channel ID (enable Developer Mode in Discord settings if needed)

---

Configuration

All config lives in .env (created by npm run setup or copy from .env.example):

# X.com API credentials
AUTH_TOKEN=your_auth_token_here
CT0=your_ct0_cookie_here

# Discord
DISCORD_BOT_TOKEN=your_bot_token
DISCORD_ACCOUNT_CHANNEL_ID=channel_id_for_account_alerts
DISCORD_RESEARCH_CHANNEL_ID=channel_id_for_topic_research
DISCORD_MAIN_CHANNEL_ID=channel_id_for_hot_trend_pings

# Optional — auto-detected if blank
BIRD_PATH=bird
CHROME_PATH=
CHROME_CDP_PORT=18803

# OpenClaw agent used for AI insights
OPENCLAW_AGENT=dataulu

---

Quick Start (After Setup)

Manage Monitored Accounts

# Add an account
npm run accounts -- add elonmusk

# Remove an account
npm run accounts -- remove elonmusk

# List all monitored accounts
npm run accounts -- list

# Show status
npm run accounts -- status

Manage Research Topics

# Add a topic
npm run topics -- add "openclaw"

# Remove a topic
npm run topics -- remove "openclaw"

# List active topics
npm run topics -- list

# Pause/resume a topic
npm run topics -- pause "openclaw"
npm run topics -- resume "openclaw"

Run Manually

# Run account monitor once
npm run monitor

# Run topic research for a topic
npm run research -- "openclaw"

# Verify X.com session
npm run session -- verify

# Reset session (re-login)
npm run session

---

How It Works

Every 5 min (cron)                Every 6 hours (cron)
       │                                   │
       ▼                                   ▼
┌─────────────────┐            ┌──────────────────────┐
│ headless-poll.js │            │  topic-poll.js       │
│                 │            │                      │
│ bird user-tweets│            │ bird search "<topic>"│
│ → detect new    │            │ → 24h filter         │
│ → thread context│            │ → bot/spam filter    │
│ → dedup SQLite  │            │ → dedup SQLite       │
└────────┬────────┘            └──────────┬───────────┘
         │                               │
         ▼                               ▼
┌─────────────────┐            ┌──────────────────────┐
│  ai-layer.js    │            │   ai-layer.js        │
│                 │            │                      │
│ openclaw agent  │            │ openclaw agent       │
│ → 1-2 sentence  │            │ → THEMES/VIBE/SIGNAL │
│   summary       │            │   digest             │
└────────┬────────┘            └──────────┬───────────┘
         │                               │
         ▼                               ▼
┌─────────────────┐            ┌──────────────────────┐
│ format-alert.js │            │  topic-alert.js      │
│                 │            │                      │
│ Discord embed   │            │ Discord embed with   │
│ + Mute / Remove │            │ AI digest + Pause /  │
│   buttons       │            │ Search / Remove btns │
└────────┬────────┘            └──────────┬───────────┘
         │                               │
         └───────────────┬───────────────┘
                         ▼
                  Discord Channel

---

Cron Jobs

Installed automatically by bash scripts/setup-cron.sh (or via npm run setup):

To install manually:

bash scripts/setup-cron.sh

To verify:

openclaw cron list

---

OpenClaw Skill Integration

This project ships as an OpenClaw skill (SKILL.md). Once installed, your OpenClaw agent can respond to Discord slash commands:

/x-monitor

/x-monitor add elonmusk      → Start monitoring @elonmusk
/x-monitor remove elonmusk   → Stop monitoring
/x-monitor list              → List all monitored accounts
/x-monitor status            → Show health + last run

/x-research

/x-research add "openclaw"   → Start tracking topic
/x-research remove "openclaw"
/x-research list
/x-research pause "openclaw"
/x-research resume "openclaw"
/x-research status

To install the skill in your OpenClaw workspace:

cp SKILL.md PIPELINE.md ~/.openclaw/workspace/skills/x-monitor/
# or add this repo to skills.load.extraDirs in openclaw.json

Or install directly from ClawHub:

clawhub install x-monitor

---

Project Structure

x-monitor/
├── SKILL.md                    # OpenClaw / ClawHub skill manifest
├── PIPELINE.md                 # Agentic pipeline runbook (for the AI agent)
├── .env.example                # Config template — copy to .env and fill in
├── setup.js                    # Interactive setup wizard
├── src/
│   ├── config.js               # Central config loader (dotenv + validation)
│   ├── monitor/
│   │   ├── headless-poll.js    # Account monitoring engine
│   │   └── format-alert.js     # Discord embed builder (accounts)
│   ├── research/
│   │   ├── topic-poll.js       # Topic research engine
│   │   └── topic-alert.js      # Discord embed builder (topics)
│   ├── shared/
│   │   ├── db.js               # SQLite init helper
│   │   ├── discord.js          # Discord REST client
│   │   ├── bird.js