search-x

# Search X

Real-time X/Twitter search with two modes:
1. **xAI Grok** (default) — AI-powered search with x_search tool, up to 30 days
2. **X API** (`--x-api`) — Native X search, up to 7 days, pay-per-use

## Setup

### Option 1: xAI API (default)

```bash
export XAI_API_KEY="xai-YOUR-KEY"
```
Get your key at: https://console.x.ai

### Option 2: X API (native)

```bash
export X_BEARER_TOKEN="YOUR-BEARER-TOKEN"
```
Get your token at: https://console.x.com

**Note:** X API uses pay-per-usage pricing. No subscription needed.

## Commands

### Basic Search (xAI Grok)
```bash
node {baseDir}/scripts/search.js "AI video editing"
```

### Native X API Search
```bash
node {baseDir}/scripts/search.js --x-api "AI video editing"
node {baseDir}/scripts/search.js --x-api --max 50 "trending topic"  # More results
```

### Filter by Time
```bash
node {baseDir}/scripts/search.js --days 7 "breaking news"
node {baseDir}/scripts/search.js --days 1 "trending today"
node {baseDir}/scripts/search.js --x-api --days 7 "news"  # X API max is 7 days
```

### Filter by Handles
```bash
node {baseDir}/scripts/search.js --handles @elonmusk,@OpenAI "AI announcements"
node {baseDir}/scripts/search.js --exclude @bots "real discussions"
```

### Output Options
```bash
node {baseDir}/scripts/search.js --json "topic"        # Full JSON response
node {baseDir}/scripts/search.js --compact "topic"     # Just tweets, no fluff
node {baseDir}/scripts/search.js --links-only "topic"  # Just X links
```

## Example Usage in Chat

**User:** "Search X for what people are saying about Claude Code"
**Action:** Run search with query "Claude Code"

**User:** "Find tweets from @remotion_dev in the last week"
**Action:** Run search with --handles @remotion_dev --days 7

**User:** "What's trending about AI on Twitter today?"
**Action:** Run search with --days 1 "AI trending"

**User:** "Search X for Remotion best practices, last 30 days"
**Action:** Run search with --days 30 "Remotion best practices"

## How It Works

#...

# Search X — Real-time Twitter/X Search for Clawdbot

Search X/Twitter in real-time using Grok's `x_search` tool. Get actual tweets with citations.

## Installation

```bash
clawdhub install search-x
```

Or manually:
```bash
cd ~/clawd/skills && git clone https://github.com/mvanhorn/clawdbot-skill-search-x search-x
```

## Setup

Get your API key from [console.x.ai](https://console.x.ai), then:

```bash
clawdbot config set skills.entries.search-x.apiKey "xai-YOUR-KEY"
```

Or set environment variable:
```bash
export XAI_API_KEY="xai-YOUR-KEY"
```

## Usage

### Basic Search
```bash
node scripts/search.js "AI video editing"
```

### Time Filter
```bash
node scripts/search.js --days 7 "breaking news"    # Last 7 days
node scripts/search.js --days 1 "trending today"   # Last 24 hours
```

### Handle Filters
```bash
node scripts/search.js --handles @elonmusk,@OpenAI "AI"
node scripts/search.js --exclude @bots "real discussions"
```

### Output Formats
```bash
node scripts/search.js --compact "topic"      # Just tweets
node scripts/search.js --links-only "topic"   # Just URLs
node scripts/search.js --json "topic"         # Full JSON
```

## Chat Examples

Just tell your Clawdbot:
- "Search X for what people are saying about Claude"
- "Find tweets about Remotion in the last week"
- "What's trending on Twitter about AI today?"

## How It Works

Uses xAI's Responses API with the `x_search` tool:
- **Endpoint:** `/v1/responses`
- **Model:** `grok-4-1-fast` (optimized for search)
- **Features:** Date filtering, handle filtering, real citations

## Output Example

```
🔍 Searching X: "Remotion Claude Code" (last 30 days)...

**@rknkhanna** (Rahul K)
"made a launch video using remotion. the remotion team published a skill
that teaches claude their best practices. fed it my design system.
described 6 scenes. got working animation code."
https://x.com/rknkhanna/status/2014504411981295928

📎 Citations (5):
   https://x.com/i/status/2014504411981295928
   ...
```

## License

MIT