grok-skill

A Claude Code Skill that routes X/Twitter queries to xAI Grok 4 via OpenRouter with Live Search turned on and scoped to the X source.

Features

• Live Search - Real-time X/Twitter data via Grok 4's Live Search
• Handle Filtering - Multi-value --include / --exclude for targeted searches
• Date Range Queries - Time-bounded searches with calendar validation
• Engagement Filters - Filter by favorites and views
• Network Resilience - Automatic retries with exponential backoff
• Citation Extraction - Tweet URLs with fallback parsing
• Production Ready - Comprehensive error handling and validation

Quick Start

# 1. Set your OpenRouter API key
export OPENROUTER_API_KEY="sk-or-..."

# 2. Run a query (assumes Bun is installed)
bun scripts/grok.ts --q "what's trending on X about AI?"

That's it! The script returns JSON with summary, citations, and usage stats.

Install

1. Get an OpenRouter API Key

Sign up at openrouter.ai and create an API key.

2. Set Environment Variable

# Set your OpenRouter key
export OPENROUTER_API_KEY="sk-or-..."

# Verify it's set
echo "$OPENROUTER_API_KEY"

# To persist across sessions, add to your shell profile:
echo 'export OPENROUTER_API_KEY="sk-or-..."' >> ~/.zshrc
source ~/.zshrc

3. Install Bun (if needed)

# macOS/Linux
brew install bun || curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1|iex"

4. Clone and Setup

# Clone to Claude Code skills directory
git clone https://github.com/mikedemarais/grok-skill.git ~/.claude/skills/grok-skill

# Make script executable
chmod +x ~/.claude/skills/grok-skill/scripts/grok.ts

# Restart Claude Code to discover the skill

Usage

# Minimal query
bun scripts/grok.ts --q "what are people saying about account abstraction on X?"

# One-off (without shell export)
OPENROUTER_API_KEY="sk-or-..." bun scripts/grok.ts --q "latest crypto news"

# Handles + timeframe + filters
bun scripts/grok.ts \
  --q "AI developments" \
  --include "@OpenAI" "@AnthropicAI" \
  --from 2025-11-01 --to 2025-11-07 \
  --mode on --min-faves 25 --max 12

# Exclude specific handles
bun scripts/grok.ts \
  --q "crypto market sentiment" \
  --exclude "@spam_account" \
  --max 20

Flags

Flag	Type	Description	Default
--q	string	Query text (required)	-
--mode	on|off|auto	Live Search mode	auto
--include	@handle...	X handles to include (max 10)	[]
--exclude	@handle...	X handles to exclude (max 10)	[]
--from	YYYY-MM-DD	Start date for search	-
--to	YYYY-MM-DD	End date for search	-
--max	1..50	Max search results	12
--min-faves	integer	Min favorites per tweet (≥ 0)	-
--min-views	integer	Min views per tweet (≥ 0)	-

Environment Variables:

• OPENROUTER_API_KEY (required) - Your OpenRouter API key
• GROK_MODEL (optional) - Override model (default: x-ai/grok-4)

Constraints:

• --include and --exclude are mutually exclusive
• Dates must be valid calendar dates in YYYY-MM-DD format
• Handles automatically stripped of '@' prefix and normalized

Sample Output