Stop Wasting Hours on X Research—This CLI Skill Changes Everything

How many hours have you lost this week?

Scrolling X. Screenshotting threads. Copy-pasting tweets into notes apps. Trying to remember which account posted that brilliant take on AI agents three days ago. If you're a developer, researcher, or founder who relies on X for market intelligence, competitor tracking, or trend spotting, you know the pain: the platform is a goldmine wrapped in a dumpster fire of noise.

Retweets drowning signal. Reply chains that break when you try to share them. The dreaded "you've reached your rate limit" popup. And don't even get me started on trying to explain to your accountant why you need another $100/month social media tool.

What if your AI agent could do the digging for you? Not just search—actually research. Follow threads. Monitor watchlists. Deliver sourced briefings. All from the terminal you already live in, with transparent costs and zero subscription bloat.

Enter x-research-skill, the open-source X/Twitter research agent that top developers are quietly installing into Claude Code and OpenClaw. This isn't another social media dashboard. It's a precision instrument for information extraction—and it might just reclaim your afternoons.

What is x-research-skill?

x-research-skill is an open-source CLI tool created by Rohun Vora that wraps the X API into a fast, agent-ready interface for terminal-based research. Born from the frustration of existing X tools—expensive subscriptions, clunky UIs, opaque pricing—this skill was built specifically for AI-augmented development workflows.

The repository lives at github.com/rohunvora/x-research-skill and has been gaining serious traction among developers who've discovered that the best research interface is no interface at all—just natural language commands to Claude, or direct CLI invocations when you need precision.

Here's why it's trending now:

• The X API shifted to pay-per-use pricing (February 2026), killing the subscription model. x-research-skill embraces this with radical cost transparency—every search shows exactly what you spent.
• AI coding agents went mainstream. Claude Code and OpenClaw users needed native X research capabilities that don't break flow by forcing them into browsers.
• The "research stack" fragmented. Developers were duct-taping together bookmarking tools, Notion databases, and manual screenshots. x-research-skill unifies search, monitoring, and documentation into one terminal-native tool.

Unlike bloated social listening platforms, x-research-skill is read-only by design (it never posts), cache-aware (avoiding repeat API charges), and agent-native (Claude reads its SKILL.md instructions file to understand how to use it). It's the difference between hiring a research assistant and buying another SaaS subscription you'll forget to cancel.

Key Features That Separate Signal from Noise

Agent-Native Architecture

The SKILL.md file isn't documentation—it's executable instructions. Claude Code reads this file and understands how to invoke searches, interpret results, and chain operations. You're not learning a new tool; you're teaching your existing AI agent a new skill.

Engagement-Smart Search

Raw X search is useless. x-research-skill adds post-fetch filtering that the API doesn't natively support:

• --sort likes|impressions|retweets|recent — Surface what actually resonated
• --min-likes N and --min-impressions N — Filter low-engagement noise
• --quality — One-flag activation of ≥10 likes threshold
• --no-replies — Eliminate reply-chain clutter

Cost Transparency as a Feature

Every operation displays real-time cost. The tool is architected to minimize API spend:

Thread Archaeology

X threads break when shared. Links die. Context fragments. The thread command reconstructs full conversation chains from any tweet ID—essential for researching debates, product launches, or viral explanations.

Watchlist Monitoring

Track accounts without following them. The watchlist system maintains data/watchlist.json and batch-checks multiple accounts with a single command—perfect for competitive intelligence or influencer tracking.

Multi-Format Output

Research isn't useful if you can't share it. Export as raw JSON (for pipelines), Markdown docs (for reports), or Telegram-formatted (for team channels). The --save flag auto-archives to ~/clawd/drafts/.

Use Cases: Where x-research-skill Actually Shines

1. Founder Market Intelligence

You're building in AI infrastructure. Every morning, you need to know: What are people saying about your competitors? What pain points are surfacing? What partnerships just announced?

The workflow:

# Overnight watchlist digest
bun run x-search.ts watchlist check

# Morning pulse on your space
bun run x-search.ts search "AI agents infrastructure" --quality --since 12h --sort likes

Result: 15 minutes instead of 90 minutes of scrolling. Sourced, timestamped, shareable.

2. Developer Advocate & Community Research

Your framework launched v2.0. You need authentic feedback—not the curated testimonials on your website, but the unfiltered developer reactions in threads and quote-tweets.

The workflow:

# Deep thread analysis of launch announcement
bun run x-search.ts thread LAUNCH_TWEET_ID

# Broader sentiment scan
bun run x-search.ts search "your-framework v2" --no-replies --min-likes 20 --pages 3 --markdown --save

The --markdown --save combo generates a research document you can attach to product meetings.

3. Crypto & DeFi Signal Detection

"CT" (Crypto Twitter) moves markets. But it's 90% noise, 9% recycled takes, 1% alpha. The --from shorthand lets you weight specific voices without missing broader context.

The workflow:

# Quick pulse from trusted accounts
bun run x-search.ts search "BNKR" --from voidcider --quick

# Broader scan with quality filter
bun run x-search.ts search "BNKR" --quality --since 1h --limit 20

4. Academic & Journalistic Research

You're writing about platform governance, misinformation campaigns, or internet culture. You need verifiable sources with timestamps, engagement metrics, and full thread reconstruction for citation.

The workflow:

# Reconstruct a viral misinformation chain
bun run x-search.ts thread ORIGINAL_TWEET_ID

# Find related discourse
bun run x-search.ts search "exact phrase from tweet" --pages 5 --json --save

JSON output feeds directly into data analysis pipelines (pandas, R, etc.).

Step-by-Step Installation & Setup Guide

Prerequisites

You'll need:

• Bun installed (bun.sh) — the runtime for CLI tooling
• X API Bearer Token — get one from the X Developer Portal with prepaid credits
• Claude Code or OpenClaw (optional but recommended for agentic use)

Installation

For Claude Code users:

# From your project directory
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

For OpenClaw users:

# From your workspace
mkdir -p skills
cd skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

Authentication Setup

Option A: Environment variable (recommended for security)

export X_BEARER_TOKEN="your-token-here"

Add to your ~/.bashrc, ~/.zshrc, or shell profile for persistence.

Option B: Config file

# Create the config directory if needed
mkdir -p ~/.config/env

# Add your token
echo "X_BEARER_TOKEN=your-token-here" >> ~/.config/env/global.env

⚠️ Security critical: Never inline your token in commands that AI agents might log. The SKILL.md explicitly warns that Claude Code and similar tools may capture HTTP headers in session transcripts. Use system environment variables, review agent log settings, and rotate read-only tokens regularly.

Verify Installation

cd skills/x-research
bun run x-search.ts search "test" --quick

You should see cost output and results. If you get authentication errors, double-check your X_BEARER_TOKEN.

REAL Code Examples from the Repository

Let's dissect actual commands from the README with deep technical commentary.

Example 1: The Quality-First Search Pattern

// Command: bun run x-search.ts search "crypto AI" --quality

// What happens under the hood:
// 1. API call to /2/tweets/search/recent with query "crypto AI"
// 2. Fetches up to 100 tweets (1 page = ~$0.50)
// 3. POST-FETCH filtering: drops anything with < 10 likes
//    (since X API doesn't expose min_faves as search operator)
// 4. Engagement-sorted output with cost summary

Why this matters: The X API's search operators are weaker than Twitter's web search. You can't filter by minimum likes at query time. x-research-skill's --quality flag implements this client-side, saving you from paying $0.50 for 100 tweets where 80 are bot noise with zero engagement. This is the difference between research and data landfill.

Example 2: Quick Mode — The Cost Killer

# Quick pulse check on a topic
bun run x-search.ts search "BNKR" --quick

# Quick check what someone is saying
bun run x-search.ts search "BNKR" --from voidcider --quick

# Quick quality-only results
bun run x-search.ts search "AI agents" --quality --quick

Technical breakdown of --quick:

// --quick enforces THREE cost-saving constraints:
// 
// 1. SINGLE PAGE ONLY (max 10 results displayed)
//    Prevents: forgetting --limit and accidentally fetching 5 pages ($2.50)
// 
// 2. AUTO-NOISE-FILTERS: appends -is:retweet -is:reply
//    Unless you explicitly used those operators in your query
//    This maximizes signal density in your 100-tweet page
// 
// 3. EXTENDED CACHE TTL: 1 hour instead of 15 minutes
//    Repeat "BNKR" checks within an hour = $0 API cost
//
// Cost summary prints after results — behavioral nudge toward awareness

When to use it: Breaking news, competitor checks, "did someone important say something?" — any query where speed and cost matter more than comprehensiveness.

Example 3: Watchlist Architecture for Monitoring

# Add accounts to persistent watchlist
bun run x-search.ts watchlist add username "optional note"

# Batch-check all watched accounts
bun run x-search.ts watchlist check

The data layer:

// watchlist.json structure (auto-managed in data/)
{
  "accounts": [
    {"username": "voidcider", "note": "DeFi alpha"},
    {"username": "frankdegods", "note": "NFT market intel"}
  ]
}

// watchlist check operation:
// 1. Reads watchlist.json
// 2. For each account: user lookup ($0.010) + recent posts ($0.005/post)
// 3. 5 accounts × ~50 posts = ~$2.55 (as documented)
// 4. Formats as digest with engagement metrics

Pro pattern: Combine with --save --markdown to generate automated morning briefings. Cron this at 8 AM and start your day with intelligence, not infinite scroll.

Example 4: Thread Reconstruction

# Full conversation chain from any tweet ID
bun run x-search.ts thread TWEET_ID

Why this is technically non-trivial: X's API returns tweets with conversation_id and referenced_tweets arrays, but reconstructing the actual thread tree requires recursive fetching, handling deleted tweets, and preserving reply-to relationships. x-research-skill does this server-side, delivering a linearized, readable thread — critical for research integrity when original tweets get deleted or accounts go private.

Example 5: Production-Ready Research Export

# Deep research with documentation output
bun run x-search.ts search "query" --pages 3 --quality --markdown --save

Pipeline integration:

// --save writes to ~/clawd/drafts/ with timestamped filename
// --markdown produces structured output:
//
// # Research: "query"
// **Date:** 2026-01-15T09:23:00Z
// **Cost:** $1.50 | **Pages:** 3 | **Filtered:** 47% removed by quality gate
//
// ## Top Results
// 1. [@username](link) — 1,247 likes
//    > Tweet text...
//    **Source:** [permalink](...)
//
// This feeds directly into:
// - Notion imports (via markdown)
// - Git-based research repos
// - LLM context windows for synthesis

Advanced Usage & Best Practices

The --from Shorthand: Precision Targeting

# These are equivalent — but the flag version is cleaner for scripting:
bun run x-search.ts search "BNKR from:voidcider"
bun run x-search.ts search "BNKR" --from voidcider

Best practice: Build a personal "trusted source" library — shell aliases or a wrapper script that cycles through your core follows with --quick checks. The tool won't double-add from: if your query already contains it, so these compose safely.

Cache Strategy for Cost Minimization

The cache lives in data/cache/ and respects TTLs:

• Standard mode: 15 minutes — good for active research sessions
• Quick mode: 60 minutes — optimal for monitoring workflows

Pro tip: For time-sensitive research, you can manually invalidate:

rm -rf skills/x-research/data/cache/*

Spending Guardrails

1. Set X Developer Console limits: Auto-recharge thresholds, hard caps per cycle
2. Always use --quick first: Escalate to deep research only if warranted
3. Monitor programmatically: GET /2/usage/tweets for dashboard integration
4. Leverage 24-hour deduplication: Re-run same searches within UTC day for free

Agent Session Security

The SKILL.md contains a critical security warning: AI agents may log HTTP headers including your bearer token. Mitigations:

• Use system env vars (never inline)
• Scope tokens to read-only permissions
• Review ~/.claude/ or equivalent for session transcripts
• Rotate tokens monthly if heavily used

Comparison with Alternatives

The verdict: x-research-skill wins for developers who live in terminals, use AI agents, and care about cost transparency. X Premium wins for casual browsing. Custom scripts win for masochists with free time.

FAQ

Q: Do I need a paid X API plan? A: Yes, x-research-skill requires the pay-per-use X API with prepaid credits. Sign up at console.x.com. No monthly subscription—buy credits as needed.

Q: Can this post tweets or interact with content? A: No, and intentionally so. x-research-skill is read-only for security and scope clarity. It searches, monitors, and exports—never posts, likes, or follows.

Q: Why Bun instead of Node.js? A: Bun provides faster startup, simpler TypeScript execution, and better CLI performance. If you have Bun installed, it just works. Node compatibility is possible but not officially supported.

Q: How do I use this with Claude Code specifically? A: Install to .claude/skills/x-research/, ensure X_BEARER_TOKEN is in your environment, then use natural language: "Search X for what people are saying about Opus 4.6" — Claude reads SKILL.md and invokes the tool.

Q: What's the maximum search depth? A: --pages 5 (500 tweets) is the current CLI limit. Each page costs ~$0.50. For deeper research, use --save --markdown and iterate with refined queries.

Q: Can I search beyond 7 days? A: Not yet in this skill. The X API offers full-archive search on the same pay-per-use plan, but x-research-skill currently uses /2/tweets/search/recent. Full-archive support is on the roadmap.

Q: Is my bearer token safe? A: It depends on your setup. The tool never prints tokens, but AI agents may log HTTP headers. Use system env vars, read-only tokens, and review session logs. See the Security section above.

Conclusion: Reclaim Your Research Time

x-research-skill isn't just another X tool—it's a workflow intervention. For developers already living in Claude Code or OpenClaw, it eliminates the context-switching tax of browser-based research. For cost-conscious teams, it replaces opaque SaaS subscriptions with penny-transparent API usage. For anyone who's ever lost an afternoon to X's infinite scroll, it offers structured, exportable, sourced intelligence.

The repository is actively maintained, MIT-licensed, and waiting for your first star. Install it today, run your first --quick search, and feel the strange relief of knowing exactly what your research cost you.

👉 Star x-research-skill on GitHub and start researching smarter.

What's the first topic you'll deep-dive? Drop your research workflow in the comments—I'm curious how others are solving the X noise problem.