feat: add X/Twitter social media search via Xquik

[kriptoburak]

Summary

Adds X/Twitter search as a supplementary research source. When XQUIK_API_KEY is set, the research loop searches X/Twitter for each query in parallel with Firecrawl, adding real-time social media perspectives alongside web results.

This is the first social media source for deep-research. Currently, all research comes from web search + scraping — meaning the researcher misses the real-time discourse, expert opinions, and community sentiment that lives on X/Twitter.

What it adds

Research questions like "What do developers think about X?" or "What's the community reaction to Y?" now get signal from actual social media posts, not just blog articles written days later.

Each tweet is converted to a markdown document with:

• Full tweet text
• Author info (username, name, verified badge)
• Engagement metrics (likes, retweets, replies, views)
• A note marking it as a social media source (so the LLM treats it as primary opinion, not authoritative fact)

How it works

# Just add the key — everything else is automatic
XQUIK_API_KEY="xk_your_key" npm start

# Or in .env.local
XQUIK_API_KEY="xk_your_key"

• Firecrawl searches run as before
• Xquik search runs in parallel (inside the existing Promise.all)
• Results merge into the same SearchResponse data array
• processSerpResult() processes all content the same way — no special handling needed
• Without XQUIK_API_KEY, behavior is 100% unchanged

Changes

File	What
src/xquik.ts	New — Xquik search module. Typed interfaces, search function, tweet-to-markdown mapping
src/deep-research.ts	Import xquik, run social search in parallel with Firecrawl, merge results
.env.example	Document XQUIK_API_KEY option

What's NOT changed

• Firecrawl search — untouched, still the primary web search
• processSerpResult() — unchanged, processes merged results naturally
• writeFinalReport() / writeFinalAnswer() — unchanged
• All prompts — unchanged
• Zero new npm dependencies (uses native fetch)

Cost

$0.00015 per tweet read via Xquik. A typical research session with 5 queries × 5 tweets = 25 reads = $0.00375 for the social media dimension.

SDK: @xquik/tweetclaw

Test plan

• npx tsc --noEmit — zero type errors
• npx prettier --check src/ — formatted
• Without XQUIK_API_KEY — behavior identical to before (xquikEnabled = false, Promise.resolve([]))
• With XQUIK_API_KEY — Xquik search runs in parallel, results merge into SearchResponse
• Xquik errors are caught and logged, never break the research loop (returns empty array)

Built with Claude Code