xoperator — High-Quality Twitter Automation Pipeline

English | 简体中文

xoperator is a "high-quality reply" automation pipeline designed for X / Twitter accounts. The goal is not "posting more", but continuously producing contextually relevant, high-value replies to tweets from real influential accounts / high-engagement posts under strict constraints.

• Only reply to original tweets (no reply-to-reply)
• Only target accounts with 20k–5M followers, excluding official/brand accounts (configurable)
• Only engage when interaction is genuine and we have something valuable to add
• All candidates and targets must have real API provenance (provenance-only)

This repository has been running on real accounts for extended periods. The design philosophy is "better to skip than to rely on fake data and low-quality replies."

⚠️ Project Status: Active development. Suitable for technical users with operations experience. Config formats may change without backward compatibility.

---

Prerequisites

Before using xoperator, you need to complete the following setup:

1. Install cccc Framework (Required)

xoperator is built on the cccc multi-agent collaboration framework. You must install and configure cccc before running xoperator.

→ cccc Project: https://github.com/ChesterRa/cccc

2. Model Capability Requirements (Important)

This project's operations place high demands on individual PEER agent capabilities. The model's reasoning ability and behavioral stability should be at least comparable to GLM-4.6.

Recommended models:

• Minimax M2
• Claude Sonnet 4.5
• GPT-5.1
• Or models with equivalent capability and stability

Not suitable:

• Haiku 4.5
• GPT-5.1-codex-mini
• Other lightweight/mini models

Small models lack the reasoning depth and consistency required for quality judgment, multi-step coordination, and strict threshold enforcement.

3. Register rube.app and Configure X/Twitter Connection (Required)

xoperator uses RUBE MCP (by Composio) for all Twitter operations. No direct Twitter API access is needed.

Steps:

1. Register an account at https://rube.app
2. Connect your X/Twitter account in the rube.app dashboard

4. Configure RUBE MCP in Your Agent CLI (Required)

RUBE MCP must be installed in your agent CLI. Currently supported CLIs:

• Claude Code
• Codex CLI
• Gemini CLI
• Droid
• Opencode

→ Installation instructions: See https://rube.app for your specific CLI

---

Language Support

Documentation files (README, CUSTOMIZATION): Available in multiple languages - choose your preferred version to read.

Operations files (PROJECT.md, FOREMAN_TASK.md): These are active working documents for AI agents.

• Default: English version (no suffix)
• To use other languages: Copy the content of the desired language version (e.g., PROJECT.zh-CN.md) to the main file (PROJECT.md)

---

Quick Start

Step 1: Clone Repository

git clone <this-repo-url> xoperator
cd xoperator

Step 2: Run Setup Wizard

make setup
# or
python3 tools/xop-setup.py

This copies all .sample config files to working directory:

• CONFIG.json - Technical parameters
• LONG_LIST.md / SHORT_LIST.md - Candidate lists
• state/rube.json - RUBE credential storage (auto-populated during operations)
• INFLUENCER_POOL.json - Influencer pool
• BANNED_HANDLES.txt / BANNED_PHRASES.txt - Blacklists

Step 3: Customize Your Persona (Required)

Edit PROJECT.md §1 (Account Positioning section) to define your account's persona and topic focus:

- Persona: [Your persona positioning]
- Content scope: [Your topic direction]

Detailed guide: CUSTOMIZATION.md

Step 4: Influencer Pool (Influencer List)

The Influencer pool determines which influencer accounts to monitor.

Included Default Pool

This repository includes INFLUENCER_POOL.json with real influencer data from the influx project. You can use it directly without additional setup.

Update to Latest Version (Optional)

To get the latest Influencer pool data from influx:

make update-influencer

This command:

1. Downloads influx-latest.jsonl from the influx project
2. Regenerates INFLUENCER_POOL.json with the latest influencer data

Custom Pool (Advanced)

Create your own INFLUENCER_POOL.json following the schema in INFLUENCER_POOL.schema.json.

Step 5: Verify Configuration

make diagnose

---

How It Works

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      Your Agent CLI                          │
│         (Claude Code / Codex CLI / Gemini CLI / etc.)       │
│                           │                                  │
│                     RUBE MCP Server                          │
│                    (https://rube.app)                        │
│                           │                                  │
│              Twitter API (via Composio)                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                       xoperator                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Influencer Pool   │  │ Candidate   │  │ Publishing Pipeline │  │
│  │ Management  │  │ Sourcing    │  │ (Vote → Publish)    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key Points

• No Twitter API keys needed: xoperator uses RUBE MCP exclusively. Your Twitter connection is managed through rube.app.

• RUBE credentials are automatic: When the agent (PEER) runs, it automatically obtains session_id and connection_id from RUBE MCP. Users do not need to manually configure state/rube.json — this is populated during operations.

• Agent-driven operations: The operational agents (PEERA, PEERB) run inside your configured CLI and handle all RUBE MCP interactions automatically.

Operations Flow

1. Sourcing: Agent queries RUBE MCP TWITTER_RECENT_SEARCH for tweets from Influencer pool
2. Filtering: xop-hotspot-refresh.py applies quality thresholds (followers, engagement, freshness)
3. Voting: Candidates are voted on and promoted to shortlist
4. Publishing: Agent calls RUBE MCP TWITTER_CREATION_OF_A_POST to reply

---

Core Documentation

Document	Purpose
CUSTOMIZATION.md ⭐	Customization guide (persona/topics/style) - Must read
PROJECT.md	Operations constitution (rules, standards, flow)
FOREMAN_TASK.md	Foreman task card (Foreman role only)
docs/RUBE-MCP-USAGE.md	RUBE MCP technical reference
tools/README.md	Tool scripts documentation

---

Design Principles (Real-Ops Pledge)

Full explanation in PROJECT.md §0. Key principles:

Provenance-only

Every id in LONG_LIST / SHORT_LIST must come from actual RUBE MCP fetch responses:

• Tools validate against state/hotspot/provenance.json
• Manual edits to id/source_url/author_handle will trigger lint errors

Thresholds Not Arbitrarily Lowered

• Floor values are enforced by code (peer adjustments won't bypass them)
• If fetch yields 0–1 candidates, system reports "sample too cold" rather than relaxing thresholds
• Threshold changes require Owner-level decision

Reply-first & Human-toned Writing

• Default only allows "reply to original tweet"
• Original tweets require explicit --allow-original flag
• Writing guidelines in PROJECT.md §6

---

Tool Scripts

Core Tools

Tool	Purpose
xop-setup.py ⭐	Setup wizard - copy config files
xop-reset.py ⭐	Reset operational data for new cycle
xop-cycle.py	Pipeline entry (clear/promote/publish)
xop-hotspot-refresh.py	Merge search results, build candidates
xop-lint.py	Data validation
xop-publish.py	Construct RUBE MCP publish payload
xop-influencer-derive.py	Generate Influencer pool from source data

Quick Commands

make setup        # Run setup wizard
make reset        # Clear operational data
make diagnose     # Config diagnostics
make test         # Syntax validation
make clean        # Clean cache files

---

File Structure

xoperator/
├── README.md              # This file
├── CUSTOMIZATION.md       # Customization guide
├── PROJECT.md             # Operations constitution
├── CONFIG.json            # Technical parameters
├── INFLUENCER_POOL.json         # Influencer pool (working set)
├── INFLUENCER_POOL.jsonl        # Source data (from influx)
├── LONG_LIST.md           # Candidate list
├── SHORT_LIST.md          # Active targets
├── BANNED_HANDLES.txt     # Blocked accounts
├── BANNED_PHRASES.txt     # Filtered phrases
├── tools/                 # Tool scripts
├── docs/                  # Technical documentation
├── state/                 # Runtime state
│   ├── rube.json          # RUBE credentials (auto-populated)
│   └── published.json     # Publication history
├── work/                  # Working files
│   └── hotspot/           # Search results
└── logs/                  # Audit logs

---

Routine Maintenance

Operations Cycle Reset

After completing an operations cycle:

make reset  # Clears LONG_LIST/SHORT_LIST/work/logs, preserves config

Automatically backs up to bak/pre-production-reset/

System Diagnostics

make diagnose                          # Quick check
python3 tools/xop-preflight.py --diagnose  # Full 6-item diagnostic

---

Troubleshooting

→ For detailed setup troubleshooting, see TROUBLESHOOTING.md

Common issues during operations:

RUBE MCP Connection Issues

1. Verify rube.app account is active and X account is connected
2. Check RUBE MCP is properly configured in your CLI
3. Run python3 tools/xop-preflight.py --diagnose for connection status

"Sample Too Cold" Warnings

This means current Influencer pool tweets don't meet quality thresholds. This is normal — wait for next refresh cycle rather than lowering thresholds.

Candidate Validation Errors

Run python3 tools/xop-lint.py to identify specific validation failures.

---

License

This project is licensed under the Apache License 2.0.

See: LICENSE

---

Contributing

If you're exploring "quality over quantity" X automation:

• Submit Issues for bugs or suggestions
• Submit PRs to improve code
• Share your customization cases

Note: Project in rapid iteration, config formats may change.

---

xoperator provides a reliable framework: enough constraints to block low-quality and fake data, yet enough flexibility for you to freely build upon it.