twitter

Twitter/X API Integration

This skill provides full Twitter/X API integration through OAuth 2.0 PKCE authentication. Post tweets, read timelines, engage with content, search, view trends, and manage lists.

Script Location

The CLI script is located at:

${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts

Run commands using:

pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts <command> [options]

First-Time Setup

Quick Start (Using Embedded Credentials)

Just run the auth command - no setup required:

pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts auth

A browser will open for Twitter authentication. Authorize the app and you're ready to go.

Using Your Own Credentials (Optional)

If you prefer to use your own Twitter Developer credentials:

1. Go to Twitter Developer Portal
2. Create a new project and app
3. In "User authentication settings":
   • App type: "Web App, Automated App or Bot"
   • App permissions: "Read and Write"
   • Callback URI: http://127.0.0.1:3000/callback (NOT localhost!)
   • Website URL: http://127.0.0.1:3000
4. Copy Client ID and Client Secret
5. Create ~/.config/twitter-skill/credentials.json:

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Token Storage

Tokens are looked up in this order:

1. Project-local: .claude/twitter-skill.local.json (in current project directory)
2. Global fallback: ~/.config/twitter-skill/tokens.json

This allows different projects to use different Twitter accounts, with a global default for projects without local tokens. Project-local tokens are automatically added to .gitignore.

Available Commands

Authentication

# Run OAuth flow (opens browser) - saves token to project-local .claude/
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts auth

# Run OAuth flow and save token globally (for use across all projects)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts auth --global

# Check authentication status
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts check

Response fields:

• auth: Checks token validity and expiration
• check: Returns { authenticated: boolean, user?: string, expiresAt?: string }

User Information

# Get authenticated user info
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts me

# Get authenticated user info including email
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts me --email

# Get user by username
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts user elonmusk

# Get user by ID
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts user-id 44196397

# Get multiple users by IDs (max 100, comma-separated)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts users "44196397,12,178273"

Response fields for user objects:

• id: User's unique ID
• name: Display name
• username: @handle (without the @)
• created_at: Account creation date
• description: Bio text
• location: User-provided location
• profile_image_url: Avatar URL
• protected: Whether tweets are protected
• verified: Whether account is verified
• verified_type: Type of verification (e.g., "blue", "business", "government")
• url: User's website URL
• public_metrics: Object containing:
  • followers_count: Number of followers
  • following_count: Number following
  • tweet_count: Total tweets
  • listed_count: Times listed

Posting & Deleting Tweets

# Post a new tweet
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts post "Hello from Claude Code!"

# Delete a tweet
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts delete 1234567890

Important: Always confirm with the user before posting tweets.

Response fields:

• post: Returns { id, text, url } - the url is the direct link to the posted tweet
• delete: Returns { deleted: true } on success

Reading Tweets

Note on Long-Form Content (Articles/Note Tweets): The skill automatically requests the note_tweet field. If a tweet contains long-form content (up to 25k chars), the full text will be returned in the note_tweet object within the response.

# Get specific tweet by ID
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts tweet 1234567890

# Get my recent tweets (last 10)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts tweets

# Get home timeline (last 20 tweets from followed accounts)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts timeline

Response fields for tweet objects:

• id: Tweet's unique ID
• text: Tweet content (up to 280 chars, or check note_tweet for long-form)
• author_id: User ID of the author
• created_at: When the tweet was posted
• conversation_id: Thread ID (same as first tweet in thread)
• source: App used to post (e.g., "Twitter Web App")
• lang: Detected language code
• public_metrics: Object containing:
  • retweet_count: Number of retweets
  • reply_count: Number of replies
  • like_count: Number of likes
  • quote_count: Number of quote tweets
  • bookmark_count: Number of bookmarks
  • impression_count: View count
• entities: Object containing parsed URLs, mentions, hashtags
• referenced_tweets: Array of { type, id } for retweets, quotes, replies
• note_tweet: Object with { text, entities } for long-form content

Engagement

# Like a tweet
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts like 1234567890

# Unlike a tweet
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts unlike 1234567890

# Retweet
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts retweet 1234567890

# Undo retweet
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts unretweet 1234567890

# Get users who retweeted a tweet (up to 100)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts retweeters 1234567890

Response fields:

• like/unlike: Returns { liked: boolean }
• retweet/unretweet: Returns { retweeted: boolean }
• retweeters: Returns array of user objects (see User Information section)

Bookmarks

# Get my bookmarked tweets
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts bookmarks

# Bookmark a tweet
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts bookmark 1234567890

# Remove a bookmark
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts unbookmark 1234567890

Generate a navigable HTML archive of all bookmarks (with images, author profiles, search/sort)

pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts bookmarks-archive reports/bookmarks.html

**Response fields:**
- `bookmarks`: Returns `{ tweets: [...], includes: { media: [...] } }` with tweet objects and media expansions
- `bookmark`: Returns `{ bookmarked: true }` on success
- `unbookmark`: Returns `{ bookmarked: false }` on success
- `bookmarks-archive`: Returns `{ path: string, tweets: number }` — the written file path and tweet count

### Search

```bash
# Search recent tweets (last 7 days)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts search "claude ai"

Response: Returns array of tweet objects (see Reading Tweets section). Search queries support Twitter's search operators:

• from:username - Tweets from a specific user
• to:username - Replies to a specific user
• #hashtag - Tweets with hashtag
• "exact phrase" - Exact phrase match
• -word - Exclude word
• lang:en - Filter by language

Trends

# Get personalized trending topics
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts trends

Note: This endpoint requires X Premium subscription for full data. Non-premium users may receive "Unknown" for category and post_count fields.

Response fields for trend objects:

• trend_name: The trending topic or hashtag
• category: Topic category (e.g., "Sports", "Entertainment", "Technology")
• post_count: Approximate number of posts (e.g., "10K", "100K+")
• trending_since: When the topic started trending

List Management

# Get my lists
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts lists

# Get list details
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts list 1234567890

# Get tweets from a list (last 20)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts list-tweets 1234567890

# Get list members (up to 100)
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts list-members 1234567890

# Add user to list
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts list-add <list-id> <user-id>

# Remove user from list
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts list-remove <list-id> <user-id>

# Create a new list
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts list-create "My List" --description "Description" --private

# Delete a list
pnpm tsx ${CLAUDE_PLUGIN_ROOT}/scripts/twitter.ts list-delete 1234567890

Response fields for list objects:

• id: List's unique ID
• name: List name
• description: List description
• private: Whether the list is private
• owner_id: User ID of list owner
• member_count: Number of members
• follower_count: Number of followers
• created_at: When the list was created

Response fields for operations:

• list-add: Returns { is_member: true } on success
• list-remove: Returns { is_member: false } on success
• list-delete: Returns { deleted: true } on success

Response Format

All commands output JSON with a consistent structure:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error responses:

{
  "success": false,
  "error": "Error message here"
}

Rate Limit Information

The CLI outputs rate limit info to stderr after each request:

[rate-limit] /users/me: 75/75, resets in 15m

Status indicators:

• Normal: X/Y - plenty of requests remaining
• Low: X/Y (low) - less than 50% remaining
• Critical: X/Y (CRITICAL) - less than 20% remaining

Common Workflows

Post a Tweet

1. Confirm the tweet text with the user
2. Run: post "Tweet text"
3. Return the tweet URL to the user

Check Notifications/Mentions

1. Get the timeline: timeline
2. Filter for mentions or important accounts
3. Summarize for the user

See What's Trending

1. Get trends: trends
2. Present the top trending topics
3. Search for tweets on interesting trends: search "#trending_topic"

Manage Lists

1. List existing lists: lists
2. Get members: list-members <id>
3. Add/remove members as needed

Review Bookmarks

1. Get bookmarked tweets: bookmarks
2. Review saved tweets and summarize for the user
3. Get full details on specific tweets: tweet <id>

Research a Topic

1. Search for tweets: search "topic"
2. Get specific tweets for more detail: tweet <id>
3. Get user info for context: user <username>

Analyze Tweet Engagement

1. Get the tweet: tweet <id>
2. Check public_metrics for engagement stats
3. Get retweeters: retweeters <id> to see who shared it

API Rate Limits

Twitter API v2 has rate limits. The most common:

• Tweets lookup: 300 requests per 15 minutes
• Post tweet: 200 tweets per 24 hours
• Like/Unlike: 50 per 24 hours
• Search: 180 requests per 15 minutes
• Trends: 75 requests per 15 minutes

The skill will return rate limit errors when exceeded.

Troubleshooting

"Something went wrong" during auth

• Ensure callback URL is http://127.0.0.1:3000/callback (NOT localhost)
• Check that port 3000 is not in use

Token expires quickly

• The skill automatically refreshes tokens before expiry
• If issues persist, run auth again

"Not authorized" errors

• Check that your app has the required permissions
• Run auth to re-authenticate with updated scopes

Rate limit exceeded

• Wait for the rate limit window to reset (usually 15 minutes)
• Space out requests when doing bulk operations

Trends showing "Unknown" values

• This endpoint requires X Premium subscription for full data
• Non-premium accounts will see trend names but not categories or post counts