The Problem
Teams that need up‑to‑date public sentiment from X (Twitter) must manually craft API calls, handle pagination, de‑duplicate results, and format the output for downstream tools (e.g., Claude Code or OpenClaw). The repetitive plumbing consumes developer time and incurs unnecessary API costs.
What This Does
x-research-skill wraps the X v2 API in a small TypeScript library (lib/api.ts) and a Bun‑based CLI (x-search.ts). The CLI implements the research loop used by Claude: decompose a query, call the API, filter/sort by engagement, and synthesize a markdown briefing.
Key files:
lib/api.ts – thin wrapper around the X endpoints (search, profile, thread, tweet). lib/cache.ts – file‑based cache with a 15‑minute TTL, referenced by the CLI to avoid duplicate reads. lib/format.ts – helpers that produce Telegram‑compatible markdown and plain markdown. x-search.ts – command dispatcher (search, profile, thread, tweet, watchlist) that wires the API, cache, and format layers together.
The skill also ships a SKILL.md that Claude reads directly, allowing the same functionality without the CLI.
How To Use It
Setup
Clone into the appropriate skills folder
git clone https://github.com/rohunvora/x-research-skill.git x-research
Install Bun (required for the CLI)
curl -fsSL https://bun.sh/install | bash
Install project dependencies (none beyond Bun’s standard library) cd x-research bun install # no package.json, but bun will create a lockfile if needed
Configuration
Obtain a bearer token from the X Developer Portal. Export it in the shell or place it in ~/.config/env/global.env:
export XBEARERTOKEN="YOURTOKEN"
The CLI reads process.env.XBEARERTOKEN via Bun’s built‑in env handling.
Running
Search with default sorting (likes) and a 15‑minute cache bun run x-search.ts search "Opus 4.6 trading" --limit 10
Retrieve a user’s recent tweets
bun run x-search.ts profile frankdegods
Pull a full thread
bun run x-search.ts thread 1234567890123456789
Add an account to the watchlist
bun run x-search.ts watchlist add frankdegods "monitoring NFT drops"
Optional flags (--sort, --min-likes, --json, --markdown, --save) are documented in the README and passed straight through to the CLI.
Real‑World Use
A research analyst could embed the CLI in a nightly cron job:
0 6 cd ~/skills/x-research && \
XBEARER_TOKEN=$(cat ~/.config/env/global.env) \ bun run x-search.ts watchlist check --markdown --save >> ~/research/daily.md
The script fetches the latest tweets from all watchlist accounts, formats them as markdown, and appends the result to a daily briefing file that Claude can later summarize.
Code Health & Issues
Med – No automated tests – lib/.ts contain no test files; edge cases (e.g., rate‑limit handling) are unverified. Med – No CI/CD pipeline – No .github/workflows or other CI config; builds and linting are manual. Med – Missing LICENSE – Repository lacks a license file, leaving redistribution rights ambiguous. Low – Minimal input validation – CLI forwards flags directly to the API wrapper; malformed queries or IDs could cause uncaught exceptions. Low – Hard‑coded cache TTL – cache.ts uses a fixed 15‑minute TTL; changing it requires code modification. Low – No explicit dependency list – No package.json; reliance on Bun’s implicit handling may complicate reproducibility in non‑Bun environments.
The Bottom Line
x-research-skill delivers a functional, low‑overhead way to turn X data into structured briefings for Claude Code or OpenClaw, with a useful CLI for ad‑hoc queries. The implementation is straightforward but lacks tests, CI, and a license, which raises maintenance and legal concerns for production use. It is best suited for small teams or individual analysts who can accept manual validation of edge cases and are comfortable running Bun‑based tooling.