Unleash X/Twitter Research with a Fast CLI

When building AI agents or conducting data‑driven investigations, you need a reliable way to pull conversations from X/Twitter. x‑research‑skill delivers exactly that—an end‑to‑end command‑line interface written in TypeScript that plugs right into Claude Code or OpenClaw. You get instant, cheap, and cost‑aware browsing of tweets, threads, and user activity, all while your agent can remain focused on higher‑level reasoning.

Why It Matters

• Low Barriers – No heavy UI or server setup; just Git clone, install Bun, and authenticate.
• Cost Transparency – After every query the CLI prints the exact X API cost, letting you stay within budgets.
• Cache‑Driven Savings – Repeat queries hit a 15‑minute (1‑hour in quick mode) cache, eliminating duplicate API calls.
• Quick Mode – A single page, 10‑result pulse check that keeps clicks and credits to a minimum.
• Watchlist Monitoring – Track conversations around any set of accounts, automatically alerting when new activity surfaces.

Getting Started

Below is the step‑by‑step roadmap from cloning the repo to running your first search.

Prerequisites

1. Acquire an X Bearer Token from the X Developer Portal (read‑only access is sufficient).
2. Export it to your shell export X_BEARER_TOKEN="your-token-here" or add X_BEARER_TOKEN=your-token-here to ~/.config/env/global.env.
3. Install Bun (the lightweight JavaScript runtime that powers the CLI).

Clone into Your Workspace

# For Claude Code
mkdir -p .claude/skills && cd .claude/skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

# For OpenClaw
mkdir -p skills && cd skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

Run an Example Search

cd skills/x-research
bun run x-search.ts search "OpenAI" --sort likes --limit 5

The terminal will display the tweet text, author, date, engagement metrics, and finally the cost of the request (e.g., $0.50).

Key Features Explained

Search & Sorting

Use natural language or advanced flags:

bun run x-search.ts search "AI agents" --sort impressions --since 1d

Options include:

• --sort – likes, impressions, retweets, or recent
• --since – 1h, 3h, 12h, 1d, 7d
• --min-likes, --min-impressions – post‑filtering low engagement
• --quick – limit to 10 results, auto‑hide retweets and replies

Thread Pulling

bun run x-search.ts thread <tweet_id>

Returns the complete thread with each message labeled and formatted for markdown or JSON.

User Profile and Recent Tweets

bun run x-search.ts profile @username

Shows the latest public posts from the user, respecting the same filters.

Watchlist Dashboard

bun run x-search.ts watchlist add alice "Crypto analyst"
bun run x-search.ts watchlist check

Maintains a watchlist.json locally; check scans each handle and reports new activity.

Cost Management

X’s pay‑per‑use model applies to each API call. The default rates (as of Feb 2026) are:

• Post read: $0.005
• User lookup: $0.010
• Search page (100 tweets): ~$0.50 (quick mode), $1.50 for 3 pages.
• Cached repeat queries are free.
• 24‑hour deduplication protects against double‑charging the same post.

The CLI prints a concise cost summary every run, so you always know what you’re spending. If you cross a threshold, simply top up your prepaid credits from the developer console.

Security & Token Management

Never expose your token in logs:

• The script reads X_BEARER_TOKEN from the environment or ~/.config/env/global.env.
• Do not embed the token in command lines or scripts accessed by others.
• Use only read‑only tokens for minimal privilege.
• Rotate tokens immediately if you suspect exposure.

Limitations & Future Roadmap

• Only the “recent” search endpoint is used; full‑archive search is available but not yet integrated.
• No write permissions – the tool is read‑only.
• Future releases aim to support full‑archive queries, advanced filtering, and optional graph visualizations for thread structures.

Final Thoughts

Whether you’re a data scientist building AI chatbots, a researcher aggregating social‑media insights, or an enthusiast automating tweet ingestion, x‑research‑skill gives you a powerful, zero‑friction interface to the X API. Its built‑in cache, cost reports, and quick mode keep budgets in check while you scale your research workflows from scratch.

Clone the repo, set your bearer token, and start hacking. Happy researching!