x research skill

The Problem

Clients that want Claude Code or OpenClaw to answer X/Twitter‑related questions must manually craft API calls, handle pagination, and de‑duplicate results. The friction adds latency, costs API credits, and makes prompt‑level research noisy.

What This Does

x-research-skill bundles a thin X‑API wrapper (lib/api.ts) with a 15‑minute file cache (lib/cache.ts) and output formatters (lib/format.ts). The CLI driver x-search.ts orchestrates the research loop: parse CLI flags → build a query → call the API → filter/sort → format for Telegram or Markdown.

Key files:

How It Is Wired

Execution starts at the main function in x-search.ts:367. main dispatches sub‑commands; the most common path is cmdSearch.

1. Flag processing – cmdSearch repeatedly invokes getOpt (3 callers) and getFlag (3 callers) to build an options object.
2. Query construction – cmdSearch calls search (defined in the same file).
3. Search flow – search calls: parseSince → normalises the --since flag. apiGet (from lib/api.ts) → performs the HTTP request, which itself calls getToken and sleep. parseTweets → turns the raw JSON into Tweet objects. sleep – rate‑limit handling.
4. Result handling – after the API response, search passes the tweet list to formatResearchMarkdown (via cmdSearch) and/or formatResultsTelegram (via format.ts). Both formatters rely on compactNumber (called from 4 places) and timeAgo.
5. Caching – before each API call, apiGet checks cacheKey (2 callers) and get/set in lib/cache.ts. Cache reads/writes hit the filesystem under data/cache/.

The most “blast‑radius” modules are:

• lib/api.ts – imported by 3 other modules, contains 12 functions (including the network call) and is the sole gateway to X.
• x-search.ts – imports 3 internal modules and drives 12 functions; any change here ripples through flag handling, search orchestration, and CLI behaviour.

No circular dependencies are present, and the internal call graph contains 54 resolved edges, confirming a straightforward call hierarchy.

How To Use It

# Clone the fork that contains the latest changes
git clone https://github.com/moses-y/x-research-skill.git x-research
cd x-research

# Install Bun (required runtime)
curl -fsSL https://bun.sh/install | bash

# Provide the X API bearer token (required by lib/api.ts)
export X_BEARER_TOKEN="your-token-here"

# Run a search (example: top liked tweets about "Opus 4.6")
bun run x-search.ts search "Opus 4.6" --sort likes --limit 10

Other CLI commands (profile, thread, tweet, watchlist) follow the same pattern, as documented in the README.

Real‑World Use

A research team integrates the CLI into an automated nightly job that monitors a set of accounts (watchlist.json). The script runs:

bun run x-search.ts watchlist check > ~/reports/watchlist-$(date +%F).md

The cache prevents duplicate API calls for the same query within the 15‑minute TTL, keeping costs predictable while delivering a ready‑to‑paste markdown brief for downstream LLM prompting.

Code Health & Issues

• Medium – Cognitive load – lib/api.ts has ~70 branch points in 249 lines, making it a maintenance hotspot. Refactoring into smaller strategy functions would improve readability.
• Medium – Missing tests – No test files detected; core logic (search, caching, formatting) is unverified by automated tests.
• Medium – No CI/CD – Repository lacks any .github/workflows or other pipeline definitions, so builds and tests (if added) are not gated.
• Medium – No LICENSE – Absence of a license file leaves usage and redistribution rights ambiguous.

No secrets were found in the commit history.

The Bottom Line

x-research-skill delivers a functional, low‑overhead CLI that turns X/Twitter data into LLM‑ready research briefs, with a pragmatic cache to curb API costs. The codebase is small and well‑structured but lacks automated testing, CI, and a license, and the central API wrapper is dense enough to merit refactoring before large‑scale modification. It is suitable for teams comfortable adding their own test suite and licensing clarification.