x-research

Searches X/Twitter via the X API to research topics, threads, and accounts from the terminal.

Updated Nov 9, 2023
One-click install
npx skills add https://github.com/oresttokovenko/dot-files --skill x-research-oresttokovenko
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: x-research
Source: https://github.com/oresttokovenko/dot-files/tree/main/chezmoi/dot_agents/skills/x-research
Command: npx skills add https://github.com/oresttokovenko/dot-files --skill x-research-oresttokovenko

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Gathering real-time opinions, dev discussions, and breaking news from X/Twitter normally requires writing raw API calls and parsing JSON by hand. This Skill wraps the X API into a Bun CLI so an AI agent can search tweets, pull threads, and monitor accounts with cost transparency and caching. ## Core Features & Use Cases - Search with filters: Query recent tweets with engagement sorting, time filters (--since 1h), noise removal (-is:retweet), and a cheap --quick mode for fast pulse checks. - Threads, profiles, and watchlists: Fetch full conversation threads, recent posts from any user, and monitor a watchlist of key accounts for heartbeat checks. - Agentic research loop: Decompose a question into targeted queries, follow threads, deep-dive linked content, and synthesize a sourced markdown briefing saved to disk. - Use Case: Ask your agent "What are people saying about the new Claude release?" and it runs filtered searches, follows high-engagement threads, and produces a cited research document with estimated API cost. ## Quick Start Ask your agent to search X for what people are saying about a topic, for example: "Search X for recent discussion about Bun 2.0 and summarize the top takes."

Frequently Asked Questions about x-research

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search X/Twitter from the command line?

Run `bun run x-search.ts search "your query" --sort likes --limit 10` from the skill directory. The CLI wraps the X API recent search endpoint, auto-filters retweets, sorts by engagement, and displays the estimated API cost after each search.

What X API access do I need for tweet search?

You need a bearer token from the X Developer Portal with pay-per-use prepaid credits. Set it as the X_BEARER_TOKEN environment variable or in ~/.config/env/global.env. Post reads cost $0.005 each, so a 100-tweet search page costs about $0.50.

Can I search tweets older than 7 days with the X API?

This skill currently only uses the recent search endpoint covering the last 7 days. The full-archive endpoint (/2/tweets/search/all) is available on the same pay-per-use plan but is not yet implemented in the CLI.

How do I monitor specific Twitter accounts for new posts?

Use the watchlist commands: `bun run x-search.ts watchlist add username "note"` to add accounts, then `watchlist check` to fetch recent posts from all of them. The list is stored in data/watchlist.json and works well for heartbeat-style periodic checks.

Why am I getting rate limited on X API searches?

With pay-per-use pricing, limits are governed by spending caps set in the Developer Console rather than fixed per-window quotas. If you receive a 429 error, the x-rate-limit-reset header indicates when to retry, and the CLI's built-in cache prevents repeat charges for identical queries.