@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

Related MCP server: Twitter/X MCP Server

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

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:

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