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(orXAI_API_KEY) env var - Python 3.11+ and uv (
pip install uvor 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 forfrom:usernamein 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 --quickProfile
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 recentWatchlist stored in {baseDir}/skills/x-research/data/watchlist.json.
Cache
uv run {baseDir}/skills/x-research/scripts/x_search.py cache clear15-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.comorurl:specific domains - Noise reduction:
-is:retweet(auto-added), add-is:replyif needed - Spam filter: Add
-airdrop -giveaway -whitelistfor 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
threadcommand? - 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)