# x-monitor

Adopt this skill: https://proskills.md/skills/other/whoisdhana-x-monitor

Page: https://proskills.md/skills/other/whoisdhana-x-monitor
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 3105
upstream: https://github.com/whoisdhana/x-monitor/blob/HEAD/SKILL.md

````text
---
name: x-monitor
description: "Monitor X/Twitter accounts and topics with AI-enriched Discord alerts. Cron-powered, fully agentic."
version: 1.0.0
emoji: "🐦"
metadata:
  openclaw:
    requires:
      env:
        - AUTH_TOKEN
        - CT0
        - DISCORD_BOT_TOKEN
        - DISCORD_ACCOUNT_CHANNEL_ID
        - DISCORD_RESEARCH_CHANNEL_ID
      bins:
        - bird
      anyBins:
        - google-chrome
        - chromium
    primaryEnv: AUTH_TOKEN
    os: ["macos", "linux"]
    install:
      - kind: brew
        formula: agent-reach
        bins: [bird]
        label: "Install bird CLI (agent-reach)"
---

# X Monitor + X Research

> **For the full agentic pipeline runbook** (cron jobs, error handling, self-repair), read `PIPELINE.md`.
> **For setup instructions**, see `README.md` or run `node setup.js`.

Handle Discord slash commands for X account monitoring (`/x-monitor`) and topic research (`/x-research`).

---

## /x-monitor Commands

| Action | Command |
|--------|---------|
| `add <username>` | Add an X account to monitoring |
| `remove <username>` | Remove an X account from monitoring |
| `list` | List all monitored accounts |
| `status` | Show monitoring status |
| `mute <username>` | Mute alerts for an account |

```bash
node src/cli/commands.js add <username>
node src/cli/commands.js remove <username>
node src/cli/commands.js list
node src/cli/commands.js status
```

### Response Templates

**add success:** `✅ Now monitoring @<username>`
**add error:** `❌ Error: <message>`
**remove success:** `✅ Removed @<username> from monitoring`
**list:**
```
📋 Monitoring (N accounts):
@account1, @account2, @account3
```
**status:**
```
🐦 X Monitor: Active
Monitoring N accounts
```

---

## /x-research Commands

| Action | Command |
|--------|---------|
| `add <topic>` | Start tracking a topic |
| `remove <topic>` | Stop tracking a topic |
| `list` | List active topics |
| `list-all` | List all topics including paused |
| `status` | Show topic counts (active/paused/total) |
| `pause <topic>` | Pause alerts for a topic |
| `resume <topic>` | Resume alerts for a topic |

```bash
node src/cli/topic-commands.js add "<topic>"
node src/cli/topic-commands.js remove "<topic>"
node src/cli/topic-commands.js list
node src/cli/topic-commands.js list-all
node src/cli/topic-commands.js status
node src/cli/topic-commands.js pause "<topic>"
node src/cli/topic-commands.js resume "<topic>"
```

### Response Templates

**add success:** `✅ Now tracking topic: "<topic>"`
**remove success:** `✅ Removed topic: "<topic>"`
**pause success:** `⏸ Paused topic: "<topic>"`
**resume success:** `▶️ Resumed topic: "<topic>"`
**list:**
```
🔍 Tracking N topics:
• topic one
• topic two
```
**status:**
```
🔍 X Research: Active
N active topics, N paused
```

---

## Implementation Notes

- Parse arguments to determine action, execute CLI command, send result back via `message` tool
- Use the channel from the interaction context
- Quote multi-word topics when passing to topic-commands.js
- Use ephemeral responses for confirmations where appropriate
````

## File: README.md
upstream: https://github.com/whoisdhana/x-monitor/blob/HEAD/README.md

````text
# 🐦 X Monitor

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

[![MIT-0 License](https://img.shields.io/badge/license-MIT--0-green.svg)](LICENSE)
[![OpenClaw Skill](https://img.shields.io/badge/openclaw-skill-blue.svg)](https://clawhub.ai)

---

## What It Does

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

| Feature | Details |
|---|---|
| **Account Monitor** | Polls up to N accounts every 5 min, detects new tweets, fetches thread context (first 3 replies), sends AI-summarized Discord embed |
| **Topic Research** | Searches live X every 6h per topic, filters bots/spam, sends AI-synthesized Discord digest |
| **Hot Trend Detection** | Alerts when a topic spikes 2.5× its rolling average (with 12h cooldown) |
| **AI Insights** | Uses your configured OpenClaw agent to generate 1-2 sentence summaries and structured THEMES/VIBE/SIGNAL digests |
| **Discord Buttons** | Inline Mute / Remove / Pause / Search buttons on every alert |
| **Self-Healing** | Exponential backoff on rate limits, session validation, emergency stop on combined failures |

---

## Prerequisites

| Requirement | Notes |
|---|---|
| **[OpenClaw](https://openclaw.ai)** | Must be installed and gateway running |
| **[bird CLI (agent-reach)](https://github.com/openclaw/agent-reach)** | X/Twitter API wrapper. Install: `brew install openclaw/tap/agent-reach` |
| **Google Chrome** | For session validation and thread context fetching |
| **X.com account** | Your auth cookies (`auth_token` + `ct0`) |
| **Discord bot** | With a token and permissions to post in your channels |
| **Node.js ≥ 18** | |

---

## Installation

```bash
# 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](https://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](https://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`):

```env
# 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

```bash
# 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

```bash
# 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

```bash
# 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`):

| Job | Schedule | Script |
|---|---|---|
| `x-account-monitor` | Every 5 min | `scripts/run-monitor.sh` |
| `x-topic-research` | Every 6 hours | `scripts/run-research.sh` |

To install manually:
```bash
bash scripts/setup-cron.sh
```

To verify:
```bash
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:
```bash
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:
```bash
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        
````
