x-twitter: Full Twitter/X Automation from Your Terminal

With 17,100+ downloads and 40 stars, x-twitter is one of the most-downloaded social media skills on ClawHub. Built by @annettemekuro30, it wraps the Twitter/X API into a clean CLI called twclaw — giving OpenClaw agents the ability to read, search, post, and engage on Twitter/X without writing a single line of API boilerplate.

The Problem It Solves

Every developer who has tried to automate Twitter/X knows the pain: OAuth flows, rate limit windows, cursor-based pagination, bearer tokens vs. user tokens. Even a simple "get my timeline" requires 15 minutes of setup.

x-twitter abstracts all of that. One environment variable, one binary, and your agent has full access to Twitter/X — read, write, follow, and everything in between.

Core Concept

The skill installs a Python-backed CLI called twclaw. You set TWITTER_BEARER_TOKEN (or a full OAuth key set for write operations), and every Twitter/X action becomes a one-liner your OpenClaw agent can invoke directly.

# Your only setup step
export TWITTER_BEARER_TOKEN="your_bearer_token_here"

Deep Dive

Reading the Timeline

twclaw timeline              # Your home timeline (default: 10 tweets)
twclaw home -n 20            # Explicitly 20 tweets
twclaw timeline --json       # JSON output for programmatic use

Tweets come back with author, handle, text, timestamp, and engagement counts — formatted for easy reading or piped into further processing.

Search

twclaw search "AI agents 2026"            # Keyword search
twclaw search "#OpenClaw"                  # Hashtag search
twclaw search "from:sama -filter:replies"  # Advanced operators
twclaw search "LLM" --all                 # Fetch all pages (paginate automatically)

The --all flag is particularly powerful: it automatically follows cursors and returns every matching tweet, not just the first page.

Posting and Engagement

# Post
twclaw tweet "Just shipped a new OpenClaw skill 🚀"
twclaw tweet "Check this out" --media screenshot.png
 
# Reply and quote
twclaw reply <tweet-id> "Great thread!"
twclaw quote <tweet-id> "Adding context here"
 
# Engagement
twclaw like <tweet-id>
twclaw unlike <tweet-id>
twclaw retweet <tweet-id>
twclaw unretweet <tweet-id>
twclaw bookmark <tweet-id>

Trending Topics

twclaw trending                          # Global trending
twclaw trending --woeid 23424977         # US trends (WOEID location code)
twclaw trending --woeid 1               # Worldwide

WOEID (Where On Earth ID) lets you scope trending topics to any country or city.

Managing Follows and Lists

# Follows
twclaw follow @handle
twclaw unfollow @handle
twclaw followers @handle -n 50
twclaw following @handle -n 50
 
# Lists
twclaw lists                                   # Your lists
twclaw list-timeline <list-id> -n 30          # Tweets from a list
twclaw list-add <list-id> @handle             # Add member
twclaw list-remove <list-id> @handle          # Remove member

Lists are an underused Twitter feature for agents: create a curated list of signal accounts, then list-timeline gives your agent a noise-free feed.

Output Modes

Comparison: twclaw vs. Direct API vs. MCP Twitter Tools

How to Install

clawhub install x-twitter

Set your bearer token:

export TWITTER_BEARER_TOKEN="your_bearer_token_here"

For write operations (posting, liking, following), you'll need an OAuth app with full read/write permissions — not just a bearer token. The skill's documentation covers both flows.

Practical Tips

1. Use --json for agent pipelines — raw output is great for humans, JSON is easier to parse downstream
2. Build curated lists — instead of noisy timeline searches, create a Twitter list of signal accounts and use list-timeline for focused feeds
3. Rate limit awareness — Twitter enforces strict 15-minute windows; space bulk operations and handle 429 errors gracefully
4. --all with caution — auto-pagination can burn through rate limits fast on large searches; set -n for bounded queries
5. Trending + WOEID — great for localized content strategies; look up WOEID codes for specific markets

Considerations

• API tier matters: Twitter's free tier limits post volume and search depth. For heavy automation, the Basic or Pro API tier unlocks higher rate limits.
• Write actions require user-level OAuth: Bearer tokens are read-only. Write actions (tweet, like, follow) need an OAuth app set up through the Twitter Developer portal.
• No DM support: Direct messages require elevated API access and are not included in this skill.
• Rate limits are strict: Twitter's 429s are enforced per 15-minute window. The skill surfaces these errors cleanly but doesn't auto-retry.

The Bigger Picture

Social media automation used to mean brittle browser scripts or expensive API wrappers. x-twitter represents the new model: a composable, agent-native primitive that follows Unix philosophy — do one thing well, pipe the output anywhere. Whether your agent is monitoring brand mentions, publishing content on a schedule, or tracking industry trends for a daily digest, twclaw gives it the Twitter/X access it needs in one command.

View the skill on ClawHub: x-twitter