Why This Exists

I wanted my AI agents to handle X for me. Find posts in my niche, draft replies in my voice, track what works. Not for spamming -- just a less tedious way to stay engaged when I'd rather be building things.

Most X tools make you pick between the official API and scraping. XMaster gives you both, plus the parts nobody else builds: pre-flight post analysis, engagement scoring, reply bypass, local scheduling, and a bookmarks archive that survives tweet deletions.

Install

One-liner (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/199-biotechnologies/xmaster/master/install.sh | sh

Homebrew:

brew tap 199-biotechnologies/tap
brew install xmaster

Cargo (crates.io):

cargo install xmaster

From source:

cargo install --git https://github.com/199-biotechnologies/xmaster

Quick Start

# 1. Get your X API keys from https://developer.x.com

# 2. Configure credentials
xmaster config set keys.api_key YOUR_API_KEY
xmaster config set keys.api_secret YOUR_API_SECRET
xmaster config set keys.access_token YOUR_ACCESS_TOKEN
xmaster config set keys.access_token_secret YOUR_ACCESS_TOKEN_SECRET

# 3. Verify setup
xmaster config check

# 4. Post
xmaster post "Hello from xmaster"

Optional extras:

xmaster config set keys.xai YOUR_XAI_KEY          # AI-powered search via xAI/Grok
xmaster config web-login                           # Enable reply bypass (auto-captures browser cookies)
xmaster config set style.voice "your style here"   # Agents write in your voice
xmaster config set account.premium true            # 25k char limit instead of 280

How It Works

XMaster has three backends behind one CLI:

Every command returns JSON when piped (or with --json). Exit codes are semantic: 0 success, 1 runtime error, 2 config error, 3 auth missing, 4 rate limited. Your agent always knows what happened.

┌─────────────────────────────────────────────┐
│                 CLI Layer                    │
│   clap + comfy-table (--json / human)       │
├─────────────────────────────────────────────┤
│          Command Router + Pre-flight        │
│   Analyze, score, cannibalization guard     │
├──────────┬──────────────┬───────────────────┤
│ X API v2 │  xAI / Grok  │  Web GraphQL      │
│(OAuth1.0a│(Bearer token)│  (Cookie auth +   │
│ Post,Like│ AI search,   │   transaction ID) │
│ RT, DM,  │ Trending,    │  Reply fallback   │
│ Search,  │ Semantic     │  when API blocks  │
│ Timeline)│ search       │  replies          │
├──────────┴──────────────┴───────────────────┤
│  Rate Limiter │ Intel Store │ Scheduler     │
│  (header-based)│  (SQLite)  │  (launchd)    │
├─────────────────────────────────────────────┤
│             Config (figment)                │
│   TOML + env vars + browser cookies         │
└─────────────────────────────────────────────┘

Commands

Posting and Engagement

Post options:

xmaster post "Great point!" --reply-to 1234567890      # Reply
xmaster post "This is big" --quote 1234567890           # Quote tweet
xmaster post "Check this" --media photo.jpg             # Attach media (up to 4)
xmaster post "Best language?" --poll "Rust,Go,Python"   # Create a poll
xmaster like https://x.com/user/status/1234567890       # URLs work too

Reading and Discovery

Search

Social Graph

Direct Messages

Scheduling

Posts are stored in local SQLite. No X Ads API needed. The launchd daemon fires every 5 minutes on macOS. Use --at auto to pick the best time from your engagement history.

Bookmark Intelligence

bookmarks sync archives content in SQLite. If the original tweet gets deleted, your copy survives.

Engagement Intelligence

The opportunity scorer ranks targets by reciprocity, reply ROI, size fit (adaptive to your follower count), topicality, and freshness.

Pre-Flight Analysis

analyze estimates 9 proxy signals aligned with the 2026 X algorithm and scores per goal (replies, quotes, shares, follows, impressions).

Lists

Moderation

System

For AI Agents

XMaster is built for AI agents from day one. Every command supports --json and returns structured envelopes with semantic exit codes.

# JSON output (auto-enabled when piped)
xmaster --json post "Hello from my agent"
xmaster post "Hello" | jq '.data.id'

Response envelope:

{
  "version": "1",
  "status": "success",
  "data": { "..." },
  "metadata": {
    "elapsed_ms": 342,
    "provider": "x_api"
  }
}

Exit codes: 0 = success, 1 = runtime error, 2 = config error, 3 = auth missing, 4 = rate limited.

Agent discovery:

xmaster agent-info --json
# Returns: 64 commands, 18 capabilities, 15 algorithm weights,
# measurement coverage, workflow handoffs, writing style config

Pre-flight analysis:

xmaster analyze "your tweet" --goal replies --json
# Returns per-signal scores and per-goal scores (0-100)

Works with: Claude Code, OpenClaw, or any agent that can shell out and parse JSON.

Configuration

Config lives at ~/.config/xmaster/config.toml on all platforms. Override with XMASTER_CONFIG_DIR.

xmaster config show       # View current config (keys masked)
xmaster config check      # Validate credentials
xmaster config set K V    # Set a value
xmaster config get K      # Read a value

Environment variables override the config file. Use XMASTER_ prefix with double underscore for nesting:

export XMASTER_KEYS__API_KEY=your-api-key
export XMASTER_KEYS__API_SECRET=your-api-secret
export XMASTER_KEYS__ACCESS_TOKEN=your-access-token
export XMASTER_KEYS__ACCESS_TOKEN_SECRET=your-access-token-secret
export XMASTER_KEYS__XAI=your-xai-key

Building from Source

git clone https://github.com/199-biotechnologies/xmaster
cd xmaster
cargo build --release
# Binary at target/release/xmaster

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT