Skip to content
Back to search

x-research

SkillWorks with Claude CodeGitHub

General-purpose X/Twitter research agent. Searches X for real-time perspectives, dev discussions, product feedback, cultural takes, breaking news, and expert opinions. Works like a web research agent but uses X as the source. Use when: (1) user says "x research", "search x for", "search twitter for", "what are people saying about", "what's twitter saying", "check x for", "x search", "/x-research", (2) user is working on something where recent X discourse would provide useful context (new library releases, API changes, product launches, cultural events, industry drama), (3) user wants to find what devs/experts/community thinks about a topic. NOT for: posting tweets or account management. Note: currently uses recent search (last 7 days). Full-archive search is available on the same pay-per-use X API plan but not yet implemented in this skill.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rohunvora-x-research-skill/badge.svg)](/listings/rohunvora-x-research-skill)

HTML

<a href="/listings/rohunvora-x-research-skill"><img src="/api/listings/rohunvora-x-research-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

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

OpenClaw

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 190 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: x-research
  3. description: >
  4. General-purpose X/Twitter research agent. Searches X for real-time perspectives,
  5. dev discussions, product feedback, cultural takes, breaking news, and expert opinions.
  6. Works like a web research agent but uses X as the source.
  7. Use when: (1) user says "x research", "search x for", "search twitter for",
  8. "what are people saying about", "what's twitter saying", "check x for", "x search",
  9. "/x-research", (2) user is working on something where recent X discourse would provide
  10. useful context (new library releases, API changes, product launches, cultural events,
  11. industry drama), (3) user wants to find what devs/experts/community thinks about a topic.
  12. NOT for: posting tweets or account management. Note: currently uses recent search (last 7 days). Full-archive search is available on the same pay-per-use X API plan but not yet implemented in this skill.
  13. ---
  14. # X Research
  15. General-purpose agentic research over X/Twitter. Decompose any research question into targeted searches, iteratively refine, follow threads, deep-dive linked content, and synthesize into a sourced briefing.
  16. For X API details (endpoints, operators, response format): read `references/x-api.md`.
  17. ## CLI Tool
  18. All commands run from this skill directory:
  19. ```bash
  20. cd ~/clawd/skills/x-research
  21. source ~/.config/env/global.env
  22. ```
  23. ### Search
  24. ```bash
  25. bun run x-search.ts search "<query>" [options]
  26. ```
  27. **Options:**
  28. - `--sort likes|impressions|retweets|recent` — sort order (default: likes)
  29. - `--since 1h|3h|12h|1d|7d` — time filter (default: last 7 days). Also accepts minutes (`30m`) or ISO timestamps.
  30. - `--min-likes N` — filter by minimum likes
  31. - `--min-impressions N` — filter by minimum impressions
  32. - `--pages N` — pages to fetch, 1-5 (default: 1, 100 tweets/page)
  33. - `--limit N` — max results to display (default: 15)
  34. - `--quick` — quick mode: 1 page, max 10 results, auto noise filter (`-is:retweet -is:reply`), 1hr cache, cost summary
  35. - `--from <username>` — shorthand for `from:username` in query
  36. - `--quality` — filter low-engagement tweets (≥10 likes, post-hoc)
  37. - `--no-replies` — exclude replies
  38. - `--save` — save results to `~/clawd/drafts/x-research-{slug}-{date}.md`
  39. - `--json` — raw JSON output
  40. - `--markdown` — markdown output for research docs
  41. Auto-adds `-is:retweet` unless query already includes it. All searches display estimated API cost.
  42. **Examples:**
  43. ```bash
  44. bun run x-search.ts search "BNKR" --sort likes --limit 10
  45. bun run x-search.ts search "from:frankdegods" --sort recent
  46. bun run x-search.ts search "(opus 4.6 OR claude) trading" --pages 2 --save
  47. bun run x-search.ts search "$BNKR (revenue OR fees)" --min-likes 5
  48. bun run x-search.ts search "BNKR" --quick
  49. bun run x-search.ts search "BNKR" --from voidcider --quick
  50. bun run x-search.ts search "AI agents" --quality --quick
  51. ```
  52. ### Profile
  53. ```bash
  54. bun run x-search.ts profile <username> [--count N] [--replies] [--json]
  55. ```
  56. Fetches recent tweets from a specific user (excludes replies by default).
  57. ### Thread
  58. ```bash
  59. bun run x-search.ts thread <tweet_id> [--pages N]
  60. ```
  61. Fetches full conversation thread by root tweet ID.
  62. ### Single Tweet
  63. ```bash
  64. bun run x-search.ts tweet <tweet_id> [--json]
  65. ```
  66. ### Watchlist
  67. ```bash
  68. bun run x-search.ts watchlist # Show all
  69. bun run x-search.ts watchlist add <user> [note] # Add account
  70. bun run x-search.ts watchlist remove <user> # Remove account
  71. bun run x-search.ts watchlist check # Check recent from all
  72. ```
  73. Watchlist stored in `data/watchlist.json`. Use for heartbeat integration — check if key accounts posted anything important.
  74. ### Cache
  75. ```bash
  76. bun run x-search.ts cache clear # Clear all cached results
  77. ```
  78. 15-minute TTL. Avoids re-fetching identical queries.
  79. ## Research Loop (Agentic)
  80. When doing deep research (not just a quick search), follow this loop:
  81. ### 1. Decompose the Question into Queries
  82. Turn the research question into 3-5 keyword queries using X search operators:
  83. - **Core query**: Direct keywords for the topic
  84. - **Expert voices**: `from:` specific known experts
  85. - **Pain points**: Keywords like `(broken OR bug OR issue OR migration)`
  86. - **Positive signal**: Keywords like `(shipped OR love OR fast OR benchmark)`
  87. - **Links**: `url:github.com` or `url:` specific domains
  88. - **Noise reduction**: `-is:retweet` (auto-added), add `-is:reply` if needed
  89. - **Crypto spam**: Add `-airdrop -giveaway -whitelist` if crypto topics flooding
  90. ### 2. Search and Extract
  91. Run each query via CLI. After each, assess:
  92. - Signal or noise? Adjust operators.
  93. - Key voices worth searching `from:` specifically?
  94. - Threads worth following via `thread` command?
  95. - Linked resources worth deep-diving with `web_fetch`?
  96. ### 3. Follow Threads
  97. When a tweet has high engagement or is a thread starter:
  98. ```bash
  99. bun run x-search.ts thread <tweet_id>
  100. ```
  101. ### 4. Deep-Dive Linked Content
  102. When tweets link to GitHub repos, blog posts, or docs, fetch with `web_fetch`. Prioritize links that:
  103. - Multiple tweets reference
  104. - Come from high-engagement tweets
  105. - Point to technical resources directly relevant to the question
  106. ### 5. Synthesize
  107. Group findings by theme, not by query:
  108. ```
  109. ### [Theme/Finding Title]
  110. [1-2 sentence summary]
  111. - @username: "[key quote]" (NL, NI) [Tweet](url)
  112. - @username2: "[another perspective]" (NL, NI) [Tweet](url)
  113. Resources shared:
  114. - [Resource title](url) — [what it is]
  115. ```
  116. ### 6. Save
  117. Use `--save` flag or save manually to `~/clawd/drafts/x-research-{topic-slug}-{YYYY-MM-DD}.md`.
  118. ## Refinement Heuristics
  119. - **Too much noise?** Add `-is:reply`, use `--sort likes`, narrow keywords
  120. - **Too few results?** Broaden with `OR`, remove restrictive operators
  121. - **Crypto spam?** Add `-$ -airdrop -giveaway -whitelist`
  122. - **Expert takes only?** Use `from:` or `--min-likes 50`
  123. - **Substance over hot takes?** Search with `has:links`
  124. ## Heartbeat Integration
  125. On heartbeat, can run `watchlist check` to see if key accounts posted anything notable. Flag to Frank only if genuinely interesting/actionable — don't report routine tweets.
  126. ## File Structure
  127. ```
  128. skills/x-research/
  129. ├── SKILL.md (this file)
  130. ├── x-search.ts (CLI entry point)
  131. ├── lib/
  132. │ ├── api.ts (X API wrapper: search, thread, profile, tweet)
  133. │ ├── cache.ts (file-based cache, 15min TTL)
  134. │ └── format.ts (Telegram + markdown formatters)
  135. ├── data/
  136. │ ├── watchlist.json (accounts to monitor)
  137. │ └── cache/ (auto-managed)
  138. └── references/
  139. └── x-api.md (X API endpoint reference)
  140. ```
README.md · README · 222 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # x-research
  2. X/Twitter research agent for [Claude Code](https://code.claude.com) and [OpenClaw](https://openclaw.ai). Search, filter, monitor — all from the terminal.
  3. ## What it does
  4. Wraps the X API into a fast CLI so your AI agent (or you) can search tweets, pull threads, monitor accounts, and get sourced research without writing curl commands.
  5. - **Search** with engagement sorting, time filtering, noise removal
  6. - **Quick mode** for cheap, targeted lookups
  7. - **Watchlists** for monitoring accounts
  8. - **Cache** to avoid repeat API charges
  9. - **Cost transparency** — every search shows what it cost
  10. ## Install
  11. ### Claude Code
  12. ```bash
  13. # From your project
  14. mkdir -p .claude/skills
  15. cd .claude/skills
  16. git clone https://github.com/rohunvora/x-research-skill.git x-research
  17. ```
  18. ### OpenClaw
  19. ```bash
  20. # From your workspace
  21. mkdir -p skills
  22. cd skills
  23. git clone https://github.com/rohunvora/x-research-skill.git x-research
  24. ```
  25. ## Setup
  26. 1. **X API Bearer Token** — Get one from the [X Developer Portal](https://developer.x.com)
  27. 2. **Set the env var:**
  28. ```bash
  29. export X_BEARER_TOKEN="your-token-here"
  30. ```
  31. Or save it to `~/.config/env/global.env`:
  32. ```
  33. X_BEARER_TOKEN=your-token-here
  34. ```
  35. 3. **Install Bun** (for CLI tooling): https://bun.sh
  36. ## Usage
  37. ### Natural language (just talk to Claude)
  38. - "What are people saying about Opus 4.6?"
  39. - "Search X for OpenClaw skills"
  40. - "What's CT saying about BNKR today?"
  41. - "Check what @frankdegods posted recently"
  42. ### CLI commands
  43. ```bash
  44. cd skills/x-research
  45. # Search (sorted by likes, auto-filters retweets)
  46. bun run x-search.ts search "your query" --sort likes --limit 10
  47. # Profile — recent tweets from a user
  48. bun run x-search.ts profile username
  49. # Thread — full conversation
  50. bun run x-search.ts thread TWEET_ID
  51. # Single tweet
  52. bun run x-search.ts tweet TWEET_ID
  53. # Watchlist
  54. bun run x-search.ts watchlist add username "optional note"
  55. bun run x-search.ts watchlist check
  56. # Save research to file
  57. bun run x-search.ts search "query" --save --markdown
  58. ```
  59. ### Search options
  60. ```
  61. --sort likes|impressions|retweets|recent (default: likes)
  62. --since 1h|3h|12h|1d|7d Time filter (default: last 7 days)
  63. --min-likes N Filter minimum likes
  64. --min-impressions N Filter minimum impressions
  65. --pages N Pages to fetch, 1-5 (default: 1, 100 tweets/page)
  66. --limit N Results to display (default: 15)
  67. --quick Quick mode (see below)
  68. --from <username> Shorthand for from:username in query
  69. --quality Pre-filter low-engagement tweets (min_faves:10)
  70. --no-replies Exclude replies
  71. --save Save to ~/clawd/drafts/
  72. --json Raw JSON output
  73. --markdown Markdown research doc
  74. ```
  75. ## Quick Mode
  76. `--quick` is designed for fast, cheap lookups when you just need a pulse check on a topic.
  77. **What it does:**
  78. - Forces single page (max 10 results) — reduces API reads
  79. - Auto-appends `-is:retweet -is:reply` noise filters (unless you explicitly used those operators)
  80. - Uses 1-hour cache TTL instead of the default 15 minutes
  81. - Shows cost summary after results
  82. **Examples:**
  83. ```bash
  84. # Quick pulse check on a topic
  85. bun run x-search.ts search "BNKR" --quick
  86. # Quick check what someone is saying
  87. bun run x-search.ts search "BNKR" --from voidcider --quick
  88. # Quick quality-only results
  89. bun run x-search.ts search "AI agents" --quality --quick
  90. ```
  91. **Why it's cheaper:**
  92. - Prevents multi-page fetches (biggest cost saver)
  93. - 1hr cache means repeat searches are free
  94. - Noise filters mean fewer junk results in your 100-tweet page
  95. - You see cost after every search — no surprises
  96. ## `--from` Shorthand
  97. Adds `from:username` to your query without having to type the full operator syntax.
  98. ```bash
  99. # These are equivalent:
  100. bun run x-search.ts search "BNKR from:voidcider"
  101. bun run x-search.ts search "BNKR" --from voidcider
  102. # Works with --quick and other flags
  103. bun run x-search.ts search "AI" --from frankdegods --quick --quality
  104. ```
  105. If your query already contains `from:`, the flag won't double-add it.
  106. ## `--quality` Flag
  107. Filters out low-engagement tweets (≥10 likes required). Applied post-fetch since `min_faves` isn't available as an X API search operator.
  108. ```bash
  109. bun run x-search.ts search "crypto AI" --quality
  110. ```
  111. ## Cost
  112. As of February 2026, the X API uses **pay-per-use pricing** with prepaid credits. No subscriptions, no monthly caps. You buy credits in the [Developer Console](https://console.x.com) and they're deducted per request.
  113. **Per-resource costs:**
  114. | Resource | Cost |
  115. |----------|------|
  116. | Post read | $0.005 |
  117. | User lookup | $0.010 |
  118. | Post create | $0.010 |
  119. **Search cost:** Each search page returns up to 100 posts = ~$0.50/page.
  120. | Operation | Est. cost |
  121. |-----------|-----------|
  122. | Quick search (1 page, ≤100 posts) | ~$0.50 |
  123. | Standard search (1 page) | ~$0.50 |
  124. | Deep research (3 pages) | ~$1.50 |
  125. | Profile check (user + posts) | ~$0.51 |
  126. | Watchlist check (5 accounts) | ~$2.55 |
  127. | Cached repeat (any) | free |
  128. **24-hour deduplication:** If you request the same post twice in a UTC day, you're only charged once. This means repeat searches on the same topic within a day cost less than the estimate above.
  129. **Spending controls:** Set auto-recharge thresholds and spending limits per billing cycle in the Developer Console. Failed requests are never billed.
  130. **xAI credit bonus:** Spend $200+/cycle on X API → earn 10-20% back as xAI/Grok API credits. See [pricing docs](https://docs.x.com/x-api/getting-started/pricing).
  131. **How x-search saves money:**
  132. - Cache (15min default, 1hr in quick mode) — repeat queries are free
  133. - 24-hour dedup means re-running the same search costs $0 at API level too
  134. - Quick mode prevents accidental multi-page fetches
  135. - Cost displayed after every search so you know what you're spending
  136. - `--from` targets specific users instead of broad searches
  137. - Monitor your usage programmatically: `GET /2/usage/tweets`
  138. ## File structure
  139. ```
  140. x-research/
  141. ├── SKILL.md # Agent instructions (Claude reads this)
  142. ├── x-search.ts # CLI entry point
  143. ├── lib/
  144. │ ├── api.ts # X API wrapper
  145. │ ├── cache.ts # File-based cache
  146. │ └── format.ts # Telegram + markdown formatters
  147. └── data/
  148. ├── watchlist.json # Accounts to monitor
  149. └── cache/ # Auto-managed
  150. ```
  151. ## Security
  152. **Bearer token handling:** x-search reads your token from the `X_BEARER_TOKEN` env var or `~/.config/env/global.env`. The token is never printed to stdout, but be aware:
  153. - **AI coding agents** (Claude Code, Codex, etc.) may log tool calls — including HTTP headers — in session transcripts. If you're running x-search inside an agent session, your bearer token could appear in those logs.
  154. - **Recommendations:**
  155. - Set `X_BEARER_TOKEN` as a system env var (not inline in commands)
  156. - Review your agent's session log settings
  157. - Use a token with minimal permissions (read-only)
  158. - Rotate your token if you suspect exposure
  159. ## Limitations
  160. - Search covers last 7 days only (uses `/2/tweets/search/recent` — the full-archive `/2/tweets/search/all` endpoint is available on the same pay-per-use plan but not yet implemented in this skill)
  161. - Read-only — never posts or interacts
  162. - Requires X API access with prepaid credits ([sign up](https://console.x.com))
  163. - `min_likes` / `min_retweets` search operators unavailable (filtered post-hoc instead)
  164. - Full-archive search (beyond 7 days) is available on pay-per-use (same credits). See [X API search docs](https://docs.x.com/x-api/posts/search/introduction). This skill currently only uses recent search — full-archive support coming soon.
  165. ## Star History
  166. [![Star History Chart](https://api.star-history.com/svg?repos=rohunvora/x-research-skill&type=Date)](https://star-history.com/#rohunvora/x-research-skill&Date)
  167. ## License
  168. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.