artwist-polyakov x-research
Research X/Twitter via xAI Grok API. Grok's x_search tool searches X in real-time and returns synthesized analysis with citations.
Перед запуском
Перед любым запуском скриптов создай рабочую копию скилла в /home/claude/x-research и работай уже из неё:
sh scripts/prepare_runtime.sh
cd /home/claude/x-research
prepare_runtime.sh копирует скилл и, если есть config/.env, нормализует его через sed -i: некавыченные значения с пробелами оборачиваются в кавычки в рабочей копии. Не выводи содержимое .env в ответ; при ошибке формата подскажи пользователю, какие строки нужно заключить в кавычки.
Config
Get an xAI API key at console.x.ai, then:
cp config/.env.example config/.env
Edit config/.env: paste your key into XAI_API_KEY, configure accounts and topics.
Quote any value that contains spaces so the file stays shell-compatible. Шаг подготовки также чинит некавыченные значения с пробелами в скопированном .env.
Without .env: skill works with explicit --accounts, --query, --topics.
With .env: digests and trending ready out of the box.
Category registry (same pattern as telegram-channel-parser):
X_CATEGORIES=ai,crypto # available categories
X_DEFAULT_CATEGORY=ai # default for "digest" without specifying
X_ACCOUNTS_AI_LABEL="AI & ML"
X_ACCOUNTS_AI=elonmusk,sama,AndrewYNg
X_TOPICS_AI=AI,LLM,GPT,Claude,agents,AGI
Agent algorithm for digest/trending:
- Read
config/.env - Parse
X_CATEGORIESto get available categories - For each:
X_ACCOUNTS_<ID>= handles,X_TOPICS_<ID>= topics,X_ACCOUNTS_<ID>_LABEL= name - Match user request to category label or use
X_DEFAULT_CATEGORY - Pass to script via
--accounts/--topics
Priority: --accounts/--topics explicit > category from .env > agent asks.
Details: config/README.md.
Philosophy
- Live-first — every call makes a fresh API request. Real-time data, never stale.
- Artifact store — each run saves an immutable snapshot in
cache/runs/. Use--prefer-cacheto reuse. - Structured output — digest/trending/search return JSON with individual items for machine consumption.
- Context hygiene — stdout limited to 30 lines. Full data in artifact file.
- Config-driven model — model set in
.env, auto-fallback if unavailable.
Workflow
Digest of subscribed accounts
# Default category from .env
bash scripts/digest.sh --period today
# Specific category
bash scripts/digest.sh --category crypto --period week
# Explicit accounts (no .env needed)
bash scripts/digest.sh --accounts "elonmusk,sama" --period today
Returns: structured items (author, date, summary, engagement, URL, topic) + Telegram post ideas.
Analyze a post/thread/topic
# By description
bash scripts/analyze.sh --query "Elon Musk's thread about open source AI"
# By URL
bash scripts/analyze.sh --url "https://x.com/elonmusk/status/123456" --query "context about the post"
# With time period
bash scripts/analyze.sh --query "debate about AI regulation" --period week
Returns: main thesis, key arguments, community reaction, sentiment, interesting findings, Telegram post angles.
Trending topics
# Default topics from .env
bash scripts/trending.sh --period today
# Specific topics
bash scripts/trending.sh --topics "Bitcoin,Ethereum,DeFi" --period today
# Category
bash scripts/trending.sh --category ai --period week
Returns: structured items (topic, summary, sentiment, key voices, engagement) + Telegram post ideas.
Custom search
# Free search
bash scripts/search.sh --query "Claude 4 reactions" --period week
# Search within specific accounts
bash scripts/search.sh --query "AI safety" --accounts "sama,ylecun" --period today
Returns: structured items + narrative summary + Telegram post ideas.
Reuse previous results
# Read last digest without making an API call
bash scripts/digest.sh --category ai --period today --prefer-cache
# Find artifact manually
bash scripts/find_latest.sh --script digest --category ai --period today
Scripts
bash scripts/<script>.sh [params]
| Script | Description | Key params |
|---|---|---|
digest.sh |
Digest of subscribed accounts | --category, --accounts, --period |
analyze.sh |
Deep analysis of post/thread/topic | --query, --url, --period |
trending.sh |
Trending topics by interests | --category, --topics, --period |
search.sh |
Custom search query | --query, --accounts, --period |
find_latest.sh |
Find latest cached artifact | --script, --category, --query, --period |
Common parameters
| Param | Required | Default | Description |
|---|---|---|---|
--accounts |
no | from .env | X handles, comma-separated (without @) |
--category |
no | from .env | Category ID from X_CATEGORIES |
--period |
no | today | Time range: 1h, today, yesterday, week, Nd |
--query |
varies | — | Search query or post description |
--topics |
no | from .env | Topics for trending, comma-separated |
--url |
no | — | X post URL for analyze |
--limit |
no | 30 | Max output lines |
--prefer-cache |
no | — | Use latest cached artifact if available |
--refresh |
no | — | Force live request (default behavior) |
Artifact store
Each run saves a JSON artifact in cache/runs/ with full metadata:
{
"meta": {
"script": "digest",
"category": "ai",
"handles": ["elonmusk", "sama"],
"period": "today",
"from_date": "2026-04-01",
"to_date": "2026-04-01",
"model": "grok-4-1-fast-reasoning",
"created_at": "2026-04-01T14:30:22Z",
"run_id": "a1b2c3"
},
"items": [...],
"ideas": [...],
"summary": "...",
"text": "...",
"citations": [...]
}
Index: cache/index.jsonl — one JSON line per run for fast lookup.
API limits
- x_search: max 10 handles per
allowed_x_handles(auto-batched if more) - Rate limits: tier-based, see docs.x.ai/developers/rate-limits
- Tool pricing: x_search invocations billed separately from tokens
- Model fallback: if primary model unavailable (HTTP 422/400), auto-retry with
grok-4.20-reasoning
Limitations
- Only public posts (x_search does not access private/protected accounts)
- x_search is a server-side Grok tool — we get synthesized analysis, not raw post data
- Structured JSON output depends on model compliance; fallback to plain text if parsing fails
- No DM access, no analytics data (only public engagement metrics)
Advanced scenarios: references/API_REFERENCE.md