x-research

X Research

Agentic research over X/Twitter. Decompose research questions into targeted searches, iteratively refine, follow threads, deep-dive linked content, and synthesize sourced briefings.

For X API details (endpoints, operators, response format): read {baseDir}/skills/x-research/references/x-api.md.

Prerequisites

• X API Bearer Token -- set X_BEARER_TOKEN (or XAI_API_KEY) env var
• Python 3.11+ and uv (pip install uv or https://docs.astral.sh/uv/)

CLI Tool

All commands use uv run for automatic dependency management:

Search

uv run {baseDir}/skills/x-research/scripts/x_search.py search "<query>" [options]

Options:

• --sort likes|impressions|retweets|recent -- sort order (default: likes)
• --since 1h|3h|12h|1d|7d -- time filter (default: last 7 days)
• --min-likes N -- filter by minimum likes
• --min-impressions N -- filter by minimum impressions
• --pages N -- pages to fetch, 1-5 (default: 1, 100 tweets/page)
• --limit N -- max results to display (default: 15)
• --quick -- quick mode: 1 page, max 10 results, auto noise filter, 1hr cache
• --from-user <username> -- shorthand for from:username in query
• --quality -- filter low-engagement tweets (min 10 likes, post-hoc)
• --no-replies -- exclude replies
• --save -- save results to ~/x-research-output/
• --json -- raw JSON output
• --markdown -- markdown output for research docs

Auto-adds -is:retweet unless query already includes it. All searches display estimated API cost.

Examples:

uv run {baseDir}/skills/x-research/scripts/x_search.py search "claude code" --sort likes --limit 10
uv run {baseDir}/skills/x-research/scripts/x_search.py search "from:anthropic" --sort recent
uv run {baseDir}/skills/x-research/scripts/x_search.py search "(cursor OR windsurf) AI editor" --pages 2 --save
uv run {baseDir}/skills/x-research/scripts/x_search.py search "AI agents" --quick
uv run {baseDir}/skills/x-research/scripts/x_search.py search "AI agents" --quality --quick

Profile

uv run {baseDir}/skills/x-research/scripts/x_search.py profile <username> [--count N] [--replies] [--json]

Fetches recent tweets from a specific user (excludes replies by default).

Thread

uv run {baseDir}/skills/x-research/scripts/x_search.py thread <tweet_id> [--pages N]

Fetches full conversation thread by root tweet ID.

Single Tweet

uv run {baseDir}/skills/x-research/scripts/x_search.py tweet <tweet_id> [--json]

Watchlist

uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist                        # Show all
uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist add <user> [note]      # Add account
uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist remove <user>           # Remove
uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist check                   # Check recent

Watchlist stored in {baseDir}/skills/x-research/data/watchlist.json.

Cache

uv run {baseDir}/skills/x-research/scripts/x_search.py cache clear

15-minute TTL. Avoids re-fetching identical queries.

Research Loop (Agentic)

When doing deep research (not just a quick search), follow this loop:

1. Decompose the Question into Queries

Turn the research question into 3-5 keyword queries using X search operators:

• Core query: Direct keywords for the topic
• Expert voices: from: specific known experts
• Pain points: Keywords like (broken OR bug OR issue OR migration)
• Positive signal: Keywords like (shipped OR love OR fast OR benchmark)
• Links: url:github.com or url: specific domains
• Noise reduction: -is:retweet (auto-added), add -is:reply if needed
• Spam filter: Add -airdrop -giveaway -whitelist for crypto-adjacent topics

2. Search and Extract

Run each query via CLI. After each, assess:

• Signal or noise? Adjust operators.
• Key voices worth searching from: specifically?
• Threads worth following via thread command?
• Linked resources worth deep-diving with WebFetch?

3. Follow Threads

When a tweet has high engagement or is a thread starter:

uv run {baseDir}/skills/x-research/scripts/x_search.py thread <tweet_id>

4. Deep-Dive Linked Content

When tweets link to GitHub repos, blog posts, or docs, fetch with WebFetch. Prioritize links that:

• Multiple tweets reference
• Come from high-engagement tweets
• Point to technical resources directly relevant to the question

5. Synthesize

Group findings by theme, not by query:

### [Theme/Finding Title]

[1-2 sentence summary]

- @username: "[key quote]" (NL, NI) [Tweet](url)
- @username2: "[another perspective]" (NL, NI) [Tweet](url)

Resources shared:
- [Resource title](url) -- [what it is]

6. Save

Use --save flag or save manually.

Refinement Heuristics

• Too much noise? Add -is:reply, use --sort likes, narrow keywords
• Too few results? Broaden with OR, remove restrictive operators
• Spam flooding results? Add -$ -airdrop -giveaway -whitelist
• Expert takes only? Use from: or --min-likes 50
• Substance over hot takes? Search with has:links

When to Use

• Researching what developers/experts/community thinks about a topic
• Getting real-time perspectives on breaking news or product launches
• Finding technical discussions about libraries, frameworks, or APIs
• Monitoring what key accounts are posting about
• Gathering sourced evidence for competitive analysis or market research
• Quick pulse check on a topic before deeper investigation

When NOT to Use

• Posting tweets, replying, or managing an X account (read-only tool)
• Historical research beyond 7 days (uses recent search endpoint only)
• Searching non-X platforms (use web search tools instead)
• Tasks where web search provides better results (X is best for real-time opinions, discussions, and breaking news -- not reference docs)

Cost Awareness

X API uses pay-per-use pricing ($0.005/post read, $0.01/user lookup). Quick mode keeps costs under ~$0.50/search. Always check the cost display after each search. Cache prevents duplicate charges. See references/x-api.md for full pricing.

File Structure

skills/x-research/
  SKILL.md           (this file)
  scripts/
    x_search.py      (CLI entry point, run with uv)
    x_api.py         (X API wrapper)
    x_cache.py       (file-based cache, 15min TTL)
    x_format.py      (terminal + markdown formatters)
  data/
    watchlist.json   (accounts to monitor)
    cache/           (auto-managed)
  references/
    x-api.md         (X API endpoint reference)