x-research

X/Twitter Research

Research high-performing tweets from tracked accounts, identify outliers, and optionally analyze video content for hooks and structure.

Prerequisites

• APIFY_TOKEN environment variable or in .env
• GEMINI_API_KEY environment variable or in .env (for video analysis)
• apify-client and google-genai Python packages
• Accounts configured in .claude/context/x-accounts.md

Verify setup:

python3 -c "
import os
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    pass
from apify_client import ApifyClient
assert os.environ.get('APIFY_TOKEN'), 'APIFY_TOKEN not set'
" && echo "Prerequisites OK"

Workflow

1. Create Run Folder

RUN_FOLDER="x-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && echo "$RUN_FOLDER"

2. Fetch Tweets

python3 .claude/skills/x-research/scripts/fetch_tweets.py \
  --days 30 \
  --max-items 100 \
  --output {RUN_FOLDER}/raw.json

Parameters:

• --days: Days back to search (default: 30)
• --max-items: Max tweets per account (default: 100)
• --handles: Override accounts file with specific handles

API Limits: Minimum 50 tweets per query required. Wait a couple minutes between runs.

3. Identify Outliers

python3 .claude/skills/x-research/scripts/analyze_posts.py \
  --input {RUN_FOLDER}/raw.json \
  --output {RUN_FOLDER}/outliers.json \
  --threshold 2.0

Output JSON contains:

• total_posts: Number of tweets analyzed
• outlier_count: Number of outliers found
• topics: Top hashtags, mentions, and keywords
• content_patterns: Analysis of what formats perform well
• accounts: List of accounts analyzed
• outliers: Array of outlier tweets with engagement metrics

4. Analyze Videos with AI (Optional)

If outliers contain video content:

python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py \
  --input {RUN_FOLDER}/outliers.json \
  --output {RUN_FOLDER}/video-analysis.json \
  --platform x \
  --max-videos 5