@talocode/x-agent

Open-source X research and human-approved publishing assistant — CLI, SDK, MCP, REST API, and AI agent skill packs.

npm install -g @talocode/x-agent

# Real "click Authorize on X" (OAuth 2.0 PKCE)
x-agent auth oauth --client-id YOUR_CLIENT_ID

# Or paste an existing token
x-agent auth login --bearer YOUR_X_BEARER_TOKEN

Features

• Search — tweets, users, trends, conversations
• Post — tweets, replies, threads with AI drafting
• Analyze — Phoenix algorithm scoring (19 engagement signals)
• Monitor — watch keywords, accounts, trends
• Safety gate — posting and replies require X_AGENT_ALLOW_WRITE=true at execution time
• Analytics — query owned-post impressions, engagement, media views, clicks, and follows
• Video primitives — initialize, append, and finalize an explicit user-approved chunked upload
• CLI — full terminal interface
• SDK — XAgentClient for programmatic use
• MCP — 19+ tools for any MCP-compatible agent
• REST API — HTTP server for remote integrations
• Skills — agent skill packs for Claude Code, OpenCode, Cursor

Quick Start

# Install
npm install -g @talocode/x-agent

# Sign in with X (browser Authorize + local callback)
# Register callback in the X developer portal: http://127.0.0.1:8787/callback
x-agent auth oauth --client-id YOUR_CLIENT_ID

# Headless / remote: print URL and paste the redirect after authorizing
x-agent auth oauth --client-id YOUR_CLIENT_ID --manual

# Search tweets
x-agent search tweets "open source AI"

# Draft content
x-agent post draft --topic "building with MCP" --tone educational

# Score against Phoenix algorithm
x-agent analyze score "Your tweet text here"

# Start MCP server
x-agent mcp

# Start REST API
x-agent serve

OAuth 2.0 (click Authorize on X)

x-agent implements OAuth 2.0 with PKCE for user-context access (post as the account that clicks Authorize).

1. In the X developer portal, create/select an app and enable OAuth 2.0.
2. Set Type of App to a type that supports the Authorization Code + PKCE flow.
3. Add an exact Callback URI / Redirect URL, for example:

   http://127.0.0.1:8787/callback
   

4. Copy the Client ID (and Client Secret if the app is confidential).
5. Run:

   x-agent auth oauth --client-id YOUR_CLIENT_ID
   # confidential apps:
   x-agent auth oauth --client-id YOUR_CLIENT_ID --client-secret YOUR_SECRET

6. A browser opens X’s Authorize screen. Approve as @yourhandle (e.g. @AbdMuizAdeyemo).
7. The local callback saves tokens to ~/.config/x-agent/tokens.json (mode 600).
8. Verify: x-agent auth status then x-agent profile get --username yourhandle.

Default scopes: tweet.read tweet.write users.read offline.access.
Override with --scope "tweet.read tweet.write users.read offline.access like.write media.write".

If the browser cannot reach localhost (remote shell, Termux without loopback), use:

x-agent auth oauth --client-id YOUR_CLIENT_ID --manual

Then paste the full redirect URL from the address bar after authorizing.

Refresh when the access token expires:

x-agent auth refresh

Environment variable alternatives: X_CLIENT_ID, X_CLIENT_SECRET, X_REDIRECT_URI, X_BEARER_TOKEN, X_REFRESH_TOKEN.

Automation Boundaries

Use read-only tools for research, trends, and analysis. Posting and replying are explicit human-approved actions and require X_AGENT_ALLOW_WRITE=true at execution time. Do not use this package for automated likes, follows, unsolicited replies, bulk direct messages, or trend-targeting.

Video publishing requires OAuth user authorization with media and post write permissions. The SDK exposes upload primitives but does not schedule or automatically publish content.

CLI Reference

Command	Description
auth oauth	OAuth 2.0 PKCE — open Authorize on X, capture callback
auth login	Paste / save API tokens manually
auth refresh	Refresh OAuth 2.0 access token
auth status	Check auth status
auth logout	Remove stored credentials
search tweets	Search tweets by keyword
search users	Search X users
search tweet <id>	Get tweet by ID
profile get	Get user profile
profile tweets	Get user's recent tweets
profile followers	Get user's followers
profile mentions	Get user's mentions
trends	View trending topics
post tweet	Post a tweet
post draft	Generate AI drafts
post reply	Reply to a tweet
post improve	Improve tweet engagement
analyze score	Phoenix algorithm scoring
analyze post	Full AI analysis
watch add	Add a watch target
watch list	List watch targets
watch check	Check watch targets
mcp	Start MCP server
serve	Start REST API server

SDK Usage

import { XAgentClient } from '@talocode/x-agent'

const client = new XAgentClient({
  tokens: { bearerToken: 'YOUR_TOKEN' }
})

const user = await client.getUser('talocode')
const score = client.scoreTweet('Your tweet text')
const drafts = await client.generateDrafts({ topic: 'AI', tone: 'educational' })

MCP Tools

19 tools for AI agents: get_user, search_tweets, post_tweet, score_tweet, generate_drafts, improve_tweet, analyze_post, and more.

REST API

x-agent serve --port 4173
curl http://localhost:4173/v1/health
curl http://localhost:4173/v1/trends
curl -X POST http://localhost:4173/v1/analyze/score -H 'Content-Type: application/json' -d '{"text":"your tweet"}'

Phoenix Algorithm

Scores posts against X's 19 engagement signals (favorite, reply, retweet, dwell, click, etc.) with weighted predictions and actionable recommendations.

Talocode ecosystem

Part of Talocode — open-source workflow layers for builders. Explore sibling projects:

Project	What it is
ScreenLane	Screen-aware voice command layer
Tera	AI chat & assistant
Codra	Local coding agent
GateLane	MCP gateway & agent tool control plane
ContextLane	Context ingestion for persistent agents
MemoryLane	Persistent agent memory
SignalLane	X growth intelligence
ReplyLane	X reply opportunity intelligence
CrawlerLane	Crawler / SEO intelligence
WebDataLane	Web extraction to structured data
SearchLane	Search layer for agents
InvoiceLane	Invoicing tools
GeoLane	Geo intelligence
UgcLane	UGC workflows
OpenSourceLane	Open-source distribution tools
StackLane	Builder stack platform
Tradia	Trading intelligence
Agent Browser	Browser automation for agents
Talocode	Org home & control plane
Skills	Shared agent skills
X Agent	X automation agent (this repo)
LaunchPix	Launch tooling
ForgeCAD	CAD workflows
WorkLane	Work automation
ClipLoop	Clip / video loops

MCP-compatible agents integrate via each product's MCP server where available (Model Context Protocol).

More: github.com/talocode · talocode.site · docs.talocode.site

License

MIT