Engagement Agent

X Agent

Algorithm-optimized X engagement. Find posts. Draft replies. Post in seconds.

X Agent monitors accounts you care about, drafts replies grounded in X's open-source Phoenix recommendation algorithm, and posts through the browser. Every reply is scored against 19 modeled engagement actions — the same signals X uses to decide what gets seen.

How it works

Five steps from post detection to reply. The agent handles discovery and drafting — you stay in control of what actually gets posted.

Watch

Add usernames to watchlist.yaml. Agent polls X API every 45 seconds.

Detect

Someone posts. You get a macOS notification with the post content instantly.

Draft

3 algorithm-optimized reply options, each scored against Phoenix signals.

Choose

Pick option 1, 2, or 3 — or type your own custom reply.

Post

Reply copies to clipboard. Opens the post in Chrome. You paste and send.

Install

$git clone https://github.com/Recusive/x-agent.git

$cd x-agent && bun install

$cp .env.example .env

$bun run test-auth

$bun run auth

Requires Claude Code CLI, Bun, and an X API developer account with pay-per-use credits.

Four ways to run

Watchlist Monitor

Add accounts to watchlist.yaml and run the watcher. Get notified the moment someone posts.

$bun run watch

Speed Reply

Paste a post URL, get 3 algorithm-scored drafts, pick one, and post. Fastest path from seeing a post to replying.

$./scripts/x-speed.sh https://x.com/user/status/123

Interactive

Claude Code session with full context. Find posts, check targets, view stats, or paste URLs for inline reply drafting.

$./scripts/x-interactive.sh

Background Daemon

Runs four monitoring loops in the background — priority, monitor, discovery, and conversations — at different intervals.

$./scripts/x-daemon.sh --bg

Phoenix algorithm scoring

Every reply is scored against X's Phoenix recommendation model — the same Grok-based transformer that decides what appears in the For You feed. These are the 19 modeled engagement actions that determine visibility.

favorite_score

Highest

Like prediction — primary ranking action in the Phoenix runner

dwell_time

High

Reading pause likelihood — modeled twice for extra weight

profile_click_score

High

Profile visit likelihood — drives follow conversion

follow_author_score

High

Follow likelihood — the growth signal

reply_score

Medium

Reply-to-reply likelihood — opens conversation threads

share_score

Medium

Sharing modeled three ways — retweet, DM share, copy-link

not_interested_score

Critical

Irrelevance risk — negative signal that subtracts from score

block_author_score

Critical

Hostility risk — kill switch that can collapse total score

What the algorithm rewards

Derived from X's open-source recommendation pipeline — not guesswork. These are structural advantages baked into how scoring and retrieval work.

First 5 minutes = 10x visibility

Thunder sorts by recency. Replying to a fresh post within minutes means the algorithm surfaces your reply before it's buried. Speed is structural, not cosmetic.

Originals over retweets

Phoenix reuses the original tweet and author for retweet scoring. RetweetDeduplicationFilter keeps only one copy. Plain retweets are weak growth instruments.

Niche consistency builds your cluster

The retrieval model uses normalized user and candidate embeddings with dot-product similarity. Stay in one lane and your embedding neighborhood strengthens.

Substance creates dwell time

Dwell is modeled twice in Phoenix. Specific, information-dense replies cause reading pauses — the algorithm notices.

Negative signals are kill switches

Block, mute, report, and not-interested actions have explicit negative heads plus score offsetting. High engagement doesn't rescue hostile content.

Monitoring loops

The daemon runs four concurrent loops at different intervals — from real-time watchlist polling to background niche discovery.

45s

Priority

Watchlist accounts from watchlist.yaml

5 min

Monitor

Extended account list and target tiers

15 min

Discovery

Niche keyword discovery for new leads

30 min

Conversations

Mentions, replies, and thread tracking

Safety constraints

You approve every reply before it posts. The agent drafts — you decide.

Maximum 20 replies per day (SQLite-tracked)

No duplicate authors per day

User approval required before every post

No links or hashtags in replies

Operating hours only: 7am-11pm

All replies go to clipboard first — you paste, you post

Configuration

Four files control everything — who to watch, how to sound, who to prioritize, and API credentials.

watchlist.yaml

Account monitoring list — who to watch for new posts

config/persona.yaml

Voice, tone, context, and algorithm rules for reply drafting

config/targets.yaml

Priority tiers, discovery keywords, community tracking

.env

API credentials (gitignored)

Example watchlist

Add the accounts you want to engage with. The agent polls them and notifies you when they post.

watchlist.yaml

# watchlist.yaml
accounts:
  - borischerny
  - karpathy
  - mattpocockuk
  - swyx

Architecture

TypeScript + Bun + SQLite + Chrome

The agent runs as a Bun process with an X API v2 client, SQLite for tracking daily reply counts and author deduplication, and browser automation for posting. Replies go through the web UI because X API v2 returns 403 errors on posts with conversation controls — the browser bypasses this for any public post you can see when logged in.

x-agent/
├── src/
│   ├── watch.ts           # Watchlist monitor
│   ├── mcp-server.ts      # Claude Code integration
│   ├── x-client.ts        # X API v2 wrapper
│   ├── store.ts           # SQLite tracking
│   ├── discover.ts        # Niche discovery
│   └── auth-setup.ts      # OAuth setup
├── scripts/
│   ├── x-daemon.sh        # Background daemon
│   ├── x-speed.sh         # Speed reply
│   └── x-interactive.sh   # Claude Code session
├── config/                # Persona + targets
├── watchlist.yaml         # Watch accounts
└── data/                  # SQLite DB (gitignored)

TypeScriptBunSQLiteX API v2Claude CodeChrome

Bundled content skill

X Agent ships with a Claude Code skill that goes beyond replies — full content strategy grounded in the algorithm source code.

Algorithm Scorecard

Score any draft against all 19 Phoenix actions with green/yellow/red ratings

First-Hour Playbook

What to do after posting — reply velocity, secondary lane, avoid cannibalization

Embedding Builder

Audit niche discipline, shift audiences with bridge content, recover from off-topic

Content Calendars

30 specific drafts per month, tied to lanes and signal objectives

Flop Diagnostics

Why a post underperformed — filter survival, stop power, OON safety, cadence

Launch Plans

Pre-launch sequence, hero post, reply plan, video plan, post-launch follow-up

Cost

$5-10

X API

Pay-per-use for search and reads

$20-30

Claude API

Reply drafting and content scoring

Approximately $30-40/month total. No subscription — pay-per-use on both APIs.

Why browser posting

X API v2 returns 403 errors when replying to posts with conversation controls enabled. The web UI doesn't have this limitation — if you can see a public post while logged in, you can reply to it. Browser posting also means your replies come from your real session with your real cookies, indistinguishable from manual posting.

Open source. MIT license.

Algorithm-grounded, not algorithm-guessing. Every optimization traces back to X's open-source recommendation pipeline.

View on GitHub Browse all skills