This repository provides x-research, a command-line interface (CLI) tool that wraps the X (formerly Twitter) API. It enables AI agents (like Claude Code, OpenClaw) and users to perform agentic searches, follow threads, monitor accounts, and retrieve sourced research directly from the terminal. Key benefits include streamlined X data retrieval, advanced search capabilities, and transparent cost reporting for API usage.

How It Works

x-research acts as a fast CLI wrapper for the X API, abstracting complex curl commands. It allows AI agents or users to search tweets, pull threads, monitor accounts, and gather sourced research. The tool features advanced search options like engagement sorting, time filtering, and noise removal, alongside a "Quick Mode" for cost-effective, targeted lookups and watchlists for account monitoring.

Quick Start & Requirements

• Installation: Clone the repository into your agent's skill directory (e.g., .claude/skills or skills).
• Setup:
  • Requires an X API Bearer Token, set via the X_BEARER_TOKEN environment variable or ~/.config/env/global.env.
  • Install Bun for CLI tooling (https://bun.sh).
• Usage:
  • Natural Language (with Claude): "What are people saying about Opus 4.6?"
  • CLI Commands (from skills/x-research): bun run x-search.ts search "query", profile username, thread TWEET_ID, watchlist add username.
  • Save output: bun run x-search.ts search "query" --save --markdown.
• Links: Bun: https://bun.sh.

Highlighted Details

• Search Options: Supports sorting (likes, impressions, recent), time filters (last 7 days default), minimum engagement filters, pagination (1-5 pages), and quality pre-filtering (--quality).
• Quick Mode (--quick): Optimizes for speed and cost by limiting results to one page (max 10), applying noise filters, using a 1-hour cache, and displaying cost summaries.
• Cost Transparency: Displays estimated API costs per search operation (e.g., ~$0.50/page) and leverages caching and 24-hour deduplication to minimize expenses.
• Shorthand Flags: --from <username> simplifies targeting specific users.

Maintenance & Community

No specific details on contributors, sponsorships, roadmap, or community channels are provided in the README.

Licensing & Compatibility

• License: MIT License.
• Compatibility: Permissive MIT license allows for commercial use and integration into closed-source projects.

Limitations & Caveats

• Search Window: Limited to the last 7 days due to using /2/tweets/search/recent; full-archive search is planned.
• Functionality: Read-only; does not post or interact with X.
• API Requirements: Requires X API access with prepaid credits.
• Filtering: min_likes/min_retweets are filtered post-hoc, not directly via API operators.
• Security: Bearer token handling requires caution; AI agents might log tokens in session transcripts.