# @talocode/x-agent

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

```bash
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

```bash
# 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](https://developer.x.com), 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:
   ```bash
   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:

```bash
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:

```bash
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

```typescript
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

```bash
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](https://github.com/talocode)** — open-source workflow layers for builders. Explore sibling projects:

| Project | What it is |
|---------|------------|
| **[ScreenLane](https://github.com/talocode/screenlane)** | Screen-aware voice command layer |
| **[Tera](https://github.com/talocode/tera)** | AI chat & assistant |
| **[Codra](https://github.com/talocode/codra)** | Local coding agent |
| **[GateLane](https://github.com/talocode/gatelane)** | MCP gateway & agent tool control plane |
| **[ContextLane](https://github.com/talocode/contextlane)** | Context ingestion for persistent agents |
| **[MemoryLane](https://github.com/talocode/memorylane)** | Persistent agent memory |
| **[SignalLane](https://github.com/talocode/signallane)** | X growth intelligence |
| **[ReplyLane](https://github.com/talocode/replylane)** | X reply opportunity intelligence |
| **[CrawlerLane](https://github.com/talocode/crawlerlane)** | Crawler / SEO intelligence |
| **[WebDataLane](https://github.com/talocode/webdatalane)** | Web extraction to structured data |
| **[SearchLane](https://github.com/talocode/searchlane)** | Search layer for agents |
| **[InvoiceLane](https://github.com/talocode/invoicelane)** | Invoicing tools |
| **[GeoLane](https://github.com/talocode/geolane)** | Geo intelligence |
| **[UgcLane](https://github.com/talocode/ugclane)** | UGC workflows |
| **[OpenSourceLane](https://github.com/talocode/opensourcelane)** | Open-source distribution tools |
| **[StackLane](https://github.com/talocode/stacklane)** | Builder stack platform |
| **[Tradia](https://github.com/talocode/tradia)** | Trading intelligence |
| **[Agent Browser](https://github.com/talocode/agent-browser)** | Browser automation for agents |
| **[Talocode](https://github.com/talocode/talocode)** | Org home & control plane |
| **[Skills](https://github.com/talocode/skills)** | Shared agent skills |
| **[X Agent](https://github.com/talocode/x-agent)** | X automation agent **(this repo)** |
| **[LaunchPix](https://github.com/talocode/launchpix)** | Launch tooling |
| **[ForgeCAD](https://github.com/talocode/forgecad)** | CAD workflows |
| **[WorkLane](https://github.com/talocode/worklane)** | Work automation |
| **[ClipLoop](https://github.com/talocode/cliploop)** | Clip / video loops |

MCP-compatible agents integrate via each product's MCP server where available ([Model Context Protocol](https://modelcontextprotocol.io/)).

More: [github.com/talocode](https://github.com/talocode) · [talocode.site](https://talocode.site) · [docs.talocode.site](https://docs.talocode.site)

## License

MIT