# x-research
X/Twitter research agent for [Claude Code](https://code.claude.com) and [OpenClaw](https://openclaw.ai). Search, filter, monitor — all from the terminal.
## What it does
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.
- **Search** with engagement sorting, time filtering, noise removal
- **Quick mode** for cheap, targeted lookups
- **Watchlists** for monitoring accounts
- **Cache** to avoid repeat API charges
- **Cost transparency** — every search shows what it cost
## Install
### Claude Code
```bash
# From your project
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/rohunvora/x-research-skill.git x-research
```
### OpenClaw
```bash
# From your workspace
mkdir -p skills
cd skills
git clone https://github.com/rohunvora/x-research-skill.git x-research
```
## Setup
1. **X API Bearer Token** — Get one from the [X Developer Portal](https://developer.x.com)
2. **Set the env var:**
```bash
export X_BEARER_TOKEN="your-token-here"
```
Or save it to `~/.config/env/global.env`:
```
X_BEARER_TOKEN=your-token-here
```
3. **Install Bun** (for CLI tooling): https://bun.sh
## Usage
### Natural language (just talk to Claude)
- "What are people saying about Opus 4.6?"
- "Search X for OpenClaw skills"
- "What's CT saying about BNKR today?"
- "Check what @frankdegods posted recently"
### CLI commands
```bash
cd skills/x-research
# Search (sorted by likes, auto-filters retweets)
bun run x-search.ts search "your query" --sort likes --limit 10
# Profile — recent tweets from a user
bun run x-search.ts profile username
# Thread — full conversation
bun run x-search.ts thread TWEET_ID
# Single tweet
bun run x-search.ts tweet TWEET_ID
# Watchlist
bun run x-search.ts watchlist add username "optional note"
bun run x-search.ts watchlist check
# Save research to file
bun run x-search.ts search "query" --save --markdown
```
### Search options
```
--sort likes|impressions|retweets|recent (default: likes)
--since 1h|3h|12h|1d|7d Time filter (default: last 7 days)
--min-likes N Filter minimum likes
--min-impressions N Filter minimum impressions
--pages N Pages to fetch, 1-5 (default: 1, 100 tweets/page)
--limit N Results to display (default: 15)
--quick Quick mode (see below)
--from <username> Shorthand for from:username in query
--quality Pre-filter low-engagement tweets (min_faves:10)
--no-replies Exclude replies
--save Save to ~/clawd/drafts/
--json Raw JSON output
--markdown Markdown research doc
```
## Quick Mode
`--quick` is designed for fast, cheap lookups when you just need a pulse check on a topic.
**What it does:**
- Forces single page (max 10 results) — reduces API reads
- Auto-appends `-is:retweet -is:reply` noise filters (unless you explicitly used those operators)
- Uses 1-hour cache TTL instead of the default 15 minutes
- Shows cost summary after results
**Examples:**
```bash
# 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
```
**Why it's cheaper:**
- Prevents multi-page fetches (biggest cost saver)
- 1hr cache means repeat searches are free
- Noise filters mean fewer junk results in your 100-tweet page
- You see cost after every search — no surprises
## `--from` Shorthand
Adds `from:username` to your query without having to type the full operator syntax.
```bash
# These are equivalent:
bun run x-search.ts search "BNKR from:voidcider"
bun run x-search.ts search "BNKR" --from voidcider
# Works with --quick and other flags
bun run x-search.ts search "AI" --from frankdegods --quick --quality
```
If your query already contains `from:`, the flag won't double-add it.
## `--quality` Flag
Filters out low-engagement tweets (≥10 likes required). Applied post-fetch since `min_faves` isn't available as an X API search operator.
```bash
bun run x-search.ts search "crypto AI" --quality
```
## Cost
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.
**Per-resource costs:**
| Resource | Cost |
|----------|------|
| Post read | $0.005 |
| User lookup | $0.010 |
| Post create | $0.010 |
**Search cost:** Each search page returns up to 100 posts = ~$0.50/page.
| Operation | Est. cost |
|-----------|-----------|
| Quick search (1 page, ≤100 posts) | ~$0.50 |
| Standard search (1 page) | ~$0.50 |
| Deep research (3 pages) | ~$1.50 |
| Profile check (user + posts) | ~$0.51 |
| Watchlist check (5 accounts) | ~$2.55 |
| Cached repeat (any) | free |
**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.
**Spending controls:** Set auto-recharge thresholds and spending limits per billing cycle in the Developer Console. Failed requests are never billed.
**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).
**How x-search saves money:**
- Cache (15min default, 1hr in quick mode) — repeat queries are free
- 24-hour dedup means re-running the same search costs $0 at API level too
- Quick mode prevents accidental multi-page fetches
- Cost displayed after every search so you know what you're spending
- `--from` targets specific users instead of broad searches
- Monitor your usage programmatically: `GET /2/usage/tweets`
## File structure
```
x-research/
├── SKILL.md # Agent instructions (Claude reads this)
├── x-search.ts # CLI entry point
├── lib/
│ ├── api.ts # X API wrapper
│ ├── cache.ts # File-based cache
│ └── format.ts # Telegram + markdown formatters
└── data/
├── watchlist.json # Accounts to monitor
└── cache/ # Auto-managed
```
## Security
**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:
- **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.
- **Recommendations:**
- Set `X_BEARER_TOKEN` as a system env var (not inline in commands)
- Review your agent's session log settings
- Use a token with minimal permissions (read-only)
- Rotate your token if you suspect exposure
## Limitations
- 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)
- Read-only — never posts or interacts
- Requires X API access with prepaid credits ([sign up](https://console.x.com))
- `min_likes` / `min_retweets` search operators unavailable (filtered post-hoc instead)
- 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.
## Star History
[](https://star-history.com/#rohunvora/x-research-skill&Date)
## License
MIT