gupsammy avatar

claude-research

Cross-platform research skills: deep multi-source research across Reddit, X, YouTube, and the web, plus a standalone YouTube research toolkit

version
0.2.4
GitHub stars
276

Install

/plugin install claude-research@Claudest

Run it inside Claude Code after adding the marketplace with /plugin marketplace add gupsammy/Claudest.

Contents

Discovered from source

Skills 2

run-research

Value Context

Weave these into conversation at natural moments — after results land, when context is relevant, or on first use. One or two per run, not all at once.

  • This isn't a single web search — it hits Reddit, X, YouTube, and web sources in parallel and cross-references findings by engagement signals. A Reddit thread with 2k upvotes carries more weight than an unsourced blog post.
  • YouTube transcript analysis is a unique capability — it reads what creators actually said, not just video titles, surfacing insights that don't appear in text-based search.
  • The --deep flag roughly doubles source coverage and adds subreddit discovery and transcript extraction — worth it for decisions with real stakes.
  • After research completes, the agent becomes a domain expert on the topic — follow-up questions are answered from the research data, not general knowledge. Prompt generation is also grounded in what real users report working.

STEP 0: Parse Intent

If $ARGUMENTS is empty, use AskUserQuestion to ask the user for the research topic before proceeding.

Extract from $ARGUMENTS:

  • TOPIC — the core subject (e.g. "Claude Code skills", "AI video tools")
  • TARGET_TOOL — specific tool/product they'll use results in, if stated (e.g. "Midjourney"). Leave as unset if not mentioned.
  • DAYS — look-back window. Default 30. Accept --days=N.
  • DEPTH — quick, default, or deep. Accept --quick / --deep. Default: default.
  • QUERY_TYPE — classify the intent:
    • RECOMMENDATIONS → "best X", "top X", "what X should I use", "recommended X"
    • NEWS → "what's happening with X", "X news", "latest on X"
    • PROMPTING → "X prompts", "prompting for X", "X techniques", "X best practices"
    • GENERAL → everything else

Depth → result limits:

DepthReddit --limitBird countYouTube count
quick15125
default503010
deep1006020

Output this block before calling any tools:

I'll research {TOPIC} across Reddit, X, YouTube, and the web (last {DAYS} days).

Parsed intent:
- TOPIC        = {TOPIC}
- TARGET_TOOL  = {TARGET_TOOL or "not specified"}
- QUERY_TYPE   = {QUERY_TYPE}
- DEPTH        = {DEPTH}

Starting research now…

Do NOT ask about TARGET_TOOL before running — research first, ask only if needed after.


STEP 1: Detect Available Sources

Run in one Bash call:

which reddit-cli 2>/dev/null && echo "REDDIT=ok" || echo "REDDIT=missing"
which bird       2>/dev/null && echo "BIRD=ok"   || echo "BIRD=missing"
which yt-dlp     2>/dev/null && echo "YTDLP=ok"  || echo "YTDLP=missing"
(which brave-cli >/dev/null 2>&1 && ([ -n "$BRAVE_API_KEY" ] || grep -q "BRAVE_API_KEY" ~/.secrets 2>/dev/null)) && echo "BRAVE=ok" || echo "BRAVE=missing"

Record REDDIT, BIRD, YTDLP, BRAVE. Always run at least web search.

Install missing tools (reddit-cli / brave-cli only)

If REDDIT=missing or BRAVE=missing, use AskUserQuestion to offer installation before proceeding. Tailor the question to which tools are missing:

  • Only REDDIT=missing → "reddit-cli is not installed. Install it now so Reddit results are included?"
  • Only BRAVE=missing → "brave-cli is not installed. Install it now for better web search coverage?"
  • Both missing → ask once, offering to install both.

If the user approves, run the installer(s) for the missing tools:

# reddit-cli
curl -fsSL https://raw.githubusercontent.com/gupsammy/reddit-cli/main/install.sh | bash

# brave-cli
curl -fsSL https://raw.githubusercontent.com/gupsammy/brave-cli/main/install.sh | sh

After installing, re-run the detection block to confirm REDDIT=ok / BRAVE=ok before proceeding.

Skip any source still marked missing without error or prompting.

If BIRD=missing or YTDLP=missing, read references/sources.md and surface the setup instructions to the user after research completes.


STEP 2: Run Sources

Run each available source fully before moving to the next. Read the complete output.

Reddit (if REDDIT=ok)

reddit-cli search "{TOPIC}" --days {DAYS} --limit {REDDIT_LIMIT} --output json

Output schema: {"items": [{id, title, url, subreddit, score, num_comments, author, date}]}

Track: post count, top subreddits, total upvotes.

For deep depth: also find relevant subreddits and drill into the top one:

reddit-cli subreddits "{TOPIC}" --by description --limit 5 --output json
reddit-cli search "{TOPIC}" --subreddit {TOP_SUB} --days {DAYS} --limit 20 --output json

Merge and deduplicate by URL.

X / Twitter (if BIRD=ok)

bird search "{TOPIC} since:$(date -v-{DAYS}d +%Y-%m-%d 2>/dev/null || date -d "{DAYS} days ago" +%Y-%m-%d)" -n {BIRD_LIMIT} --json

Track: post count, total likes, total reposts, top @handles by engagement.

YouTube (if YTDLP=ok)

python3 "${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py" search "{TOPIC}" --count {YT_COUNT} --after $(date -v-{DAYS}d +%Y%m%d 2>/dev/null || date -d "{DAYS} days ago" +%Y%m%d)

For deep depth, or when ≥1 video looks highly relevant (based on title + view count): fetch transcript of the top 1-2 results:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py" transcript "{VIDEO_URL}"

Transcripts are dense signal — read them fully and extract specific insights, not summaries.

Track: video count, total views, number of transcripts read.

Web Search

If BRAVE=ok — use brave-cli (cheaper, single binary):

brave-cli search "{TOPIC}" -n 10 --freshness month --output json
brave-cli search "{TOPIC} github OR dev.to OR medium.com" -n 5 --freshness month --output json

If BRAVE=missing — use Claude's WebSearch tool. Run 2-3 queries based on QUERY_TYPE:

  • RECOMMENDATIONS → best {TOPIC}, {TOPIC} comparison
  • NEWS → {TOPIC} news 2026, {TOPIC} announcement
  • PROMPTING → {TOPIC} prompts examples, {TOPIC} techniques
  • GENERAL → {TOPIC} 2026, {TOPIC} discussion

Exclude: reddit.com, x.com, twitter.com (already covered above). Target: blogs, docs, GitHub, dev.to, news sites.

Track: page count.


STEP 3: Judge Agent — Synthesize

Ground synthesis entirely in the actual research output, not prior knowledge.

Weight by engagement because engagement = aggregate human signal strength — a thread with 2k upvotes represents more real-world consensus than an article with no engagement metric:

  1. X posts — highest when engagement (likes + reposts) is high
  2. Reddit threads — high; engagement = upvotes + comments
  3. YouTube transcripts — high when available (dense, human-verified signal)
  4. Web pages — lower; no engagement data

Identify:

  • Patterns appearing across ≥2 sources (strongest signals)
  • Contradictions between sources (note them explicitly)
  • Top 3-5 actionable insights
  • Specific names: product names, @handles, subreddits, tools mentioned by real users

Anti-hallucination rule: If a source says "ClawdBot" and your prior knowledge maps this to something else, report what the research says. Do not conflate based on similarity to known entities.

When all findings are captured and cross-source patterns identified, proceed to STEP 4.


STEP 4: Output

If QUERY_TYPE = RECOMMENDATIONS

🏆 Most mentioned:

[Name] — {N}x mentions
Use Case: [what it does]
Sources: @handle1, r/sub1, [site name]

[Name] — {N}x mentions
...

Notable: [items with 1-2 mentions]

Every item needs a real Sources line with @handles or subreddit names from the research output.

If QUERY_TYPE = PROMPTING / NEWS / GENERAL

What I learned:

**{Finding 1}** — [1-2 sentences, per @handle or r/sub]

**{Finding 2}** — [1-2 sentences, per @handle or r/sub]

KEY PATTERNS:
1. [Pattern] — per @handle
2. [Pattern] — per r/sub
3. [Pattern] — per [YouTube channel]

Citation priority: @handles > subreddits > YouTube channels > web sites. Never cite raw URLs — use names and handles only. When a web article and an X post say the same thing, cite the X post.

Stats block (always shown, right before invitation)

Calculate real totals from the research output — never estimate.

---
✅ Research complete!
├─ 🟠 Reddit:  {N} threads │ {N} upvotes │ top: r/{sub1}, r/{sub2}
├─ 🔵 X:       {N} posts │ {N} likes │ top: @{handle1}, @{handle2}
├─ 🔴 YouTube: {N} videos │ {N} views │ {N} transcripts read
├─ 🌐 Web:     {N} pages
└─ ⚙️  Sources: {comma-separated list of sources that returned results}
---

Omit any line where the source was unavailable or returned 0 results. Use tree characters ├─ └─ │ exactly — no plain dashes.

Invitation (always last — specific, never generic)

Must reference real things from the research. Generic suggestions are a quality failure.

PROMPTING:

I'm now an expert on {TOPIC} for {TARGET_TOOL}. What do you want to make? For example:
- [specific idea based on technique people are actually using]
- [trending approach from the research data]
- [riff on what users are actually creating]

Describe your vision and I'll write a ready-to-paste prompt.

RECOMMENDATIONS:

I'm now an expert on {TOPIC}. Want to go deeper?
- [Compare specific item A vs item B from results]
- [Why {specific item} is trending right now]
- [How to get started with {specific item}]

NEWS / GENERAL:

I'm now an expert on {TOPIC}. Some things you could ask:
- [Follow-up on the biggest finding from the data]
- [Implications or next steps based on what was found]
- [Comparison or deeper dive from a specific source]

STEP 5: Wait, Then Respond

Stop after the stats + invitation block. Wait for the user to reply.

When they respond:

  • Question → Answer from the research. No new searches.
  • Go deeper → Elaborate using research findings.
  • Create something / prompt request → Write ONE prompt (see below). Never write a prompt when they asked a question.

Writing a Prompt (when requested)

One prompt only. Structure:

  1. Role/context line — tool, style, purpose
  2. Core instruction — exact task with specific parameters grounded in research
  3. Quality modifiers — from what real users report actually working, per research
  4. Output spec — format, dimensions, tone, tool-specific requirements

Every element must come from the research. No generic filler.


Resources

references/

sources.md — setup instructions for each source (reddit-cli auth, bird auth, yt-dlp install, brave-search setup).

YouTube Research

Multi-platform video research toolkit. Operates in two modes: toolkit (individual operations) and research (autonomous search-to-synthesis pipeline). All operations use a single CLI at ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py.

Run python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py <subcommand> --help for full flag reference on any subcommand.

Toolkit Mode

Invoke individual subcommands for targeted operations. Default mode when the user requests a specific action (transcript, search, metadata, audio, channel scan).

Search

Find videos matching a query. Returns structured results with metadata.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py search "<query>" --count 10

Add filters to narrow results: --min-duration 600 (seconds), --after 20250101 (YYYYMMDD), --min-views 50000. Filters are applied client-side after fetching, so the tool over-fetches automatically to compensate. Output is JSON by default; add -f text for human-readable.

Transcript

Download and clean subtitles to LLM-ready text.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript "<url>"

Outputs clean prose to stdout by default. Add --timestamps for SRT with timing cues. Add --save -t <topic> to persist to ~/youtube-research/<topic>/. Use --lang all to list available subtitle languages before downloading. Fallback chain: manual subs then auto-generated. Exit 4 if no subtitles exist in the requested language.

Metadata

Extract full video information without downloading.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py metadata "<url>"

Returns: title, description, channel, duration, chapters, view/like counts, tags, available subtitle languages, thumbnail URL. Add --playlist for playlist entry listings.

Audio

Download audio in the requested format.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py audio "<url>" --audio-format mp3 -t <topic>

Saves to ~/youtube-research/<topic>/audio/. Supported formats: mp3, m4a, opus, wav. Always saves to disk (audio cannot go to stdout). Prints the file path on success.

Channel

Scan a channel's content.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py channel "<url-or-@handle>" --limit 20

Supports tabs: --tab videos (default), shorts, streams, playlists. Filter with --after/--before (YYYYMMDD). Sort with --sort views for most-viewed-first.

Batch Processing

Any subcommand except search accepts --batch <file> (or --batch - for stdin) to process multiple URLs. One URL per line; lines starting with # or ; are skipped.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript --batch urls.txt --save -t <topic>

Research Mode

Activate when the user asks to "research", "investigate", or "find out about" a topic using YouTube as a source. This is an adaptive multi-round discovery pipeline designed for niche and emerging topics where popular videos often under-serve.

Round 1: Divergent Search

Generate 4-6 query variants that cover different angles of the topic:

  • Exact tool/concept name (e.g., "openclaw")
  • Tool + ecosystem context (e.g., "openclaw claude code")
  • Problem the tool solves (e.g., "claude code documentation framework")
  • Workflow/demo framing (e.g., "openclaw walkthrough demo")
  • Alternative names, abbreviations, or common misspellings if applicable

Spawn one Task agent per query variant simultaneously, each running:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py search "<query-variant>" --count 15

Collect all results and deduplicate by video ID. Aim for 30-50 unique candidates across all threads.

Round 1 Evaluation: Niche-First Heuristics

For niche, emerging, or edge-of-tech topics, these signals predict quality:

Positive signals (use these):

  • Title specifically names the tool or concept (not "top AI tools 2025")
  • Small channel (< 50K subscribers) — for new tech, practitioners publish before educators discover the topic
  • Technical, specific description (mentions code, config, architecture, or commands)
  • Structured content: chapters, timestamps, or detailed description
  • Recent upload date

Negative signals (treat as red flags on niche topics):

  • View count > 100K — on a narrow topic this usually means beginner-level or clickbait
  • "Tutorial for beginners" / "complete guide" in the title for brand-new tools
  • Large generalist channel covering many unrelated topics

Select 6-10 candidates from the combined pool. Note which channels produced the strongest results — those are targets for Round 2.

Round 2: Channel Discovery and Refinement

For each channel that surfaced a strong Round 1 result, scan its recent videos:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py channel "<channel-url>" --limit 20

Also run 1-2 refined search queries using specific terminology that appeared in strong Round 1 titles or descriptions. Add any new candidates to the pool.

Quality gate: If Round 1 candidates are weak (generic titles, all high-view generalist content, nothing specifically about the topic), surface this to the user and run another search round with reformulated queries before proceeding to transcripts.

Round 3: Confirm and Transcribe

From the enriched candidate pool, select 4-7 videos using the Round 1 criteria. Extract metadata to confirm relevance before committing to downloads:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py metadata "<url>"

Download transcripts in parallel — always spawn one Task agent per video, even for 2:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript "<url>" --save -t <topic>

Read each transcript and synthesize findings into a report. Use WebSearch or brave-cli to cross-reference claims or fill gaps when YouTube sources disagree or leave questions unanswered.

Research Report Format

Present the synthesis as a structured markdown report:

  • Title and one-paragraph summary of the research question
  • Key findings (3-7 bullet points of the most important takeaways across all sources)
  • Points of agreement between sources (what multiple videos confirm)
  • Points of disagreement (where sources contradict, with attribution)
  • Unique insights (notable points from individual videos not repeated elsewhere)
  • Gaps in coverage (what the sources collectively missed)
  • Sources table: video title, channel, duration, and URL for each video used

Attribute specific claims to their source video. Include timestamps when the transcript preserves them. Save all transcripts under the topic directory for future reference. See examples/research-report.md for a sample report structure.

Research Composability

See references/cli-reference.md for pipeline patterns that chain subcommands with standard Unix tools (search → jq → batch transcript).

Error Recovery

Exit CodeMeaningRecovery Action
0Success—
1Usage errorCheck --help for correct syntax
2yt-dlp not foundTell user to install: pip install yt-dlp
3Network/download errorCheck URL validity; try --cookies <browser> for private/restricted content
4No resultsFor transcripts: try --lang all to list available languages. For search: broaden query or remove filters

Platform Notes

Load references/platforms.md when processing a non-YouTube URL or when a yt-dlp command fails with exit code 3 on an unfamiliar platform. YouTube is the primary platform, but any yt-dlp-supported URL works (Vimeo, Twitter, Twitch, etc.).

After extracting a transcript, read the output and summarize key points for the user unless they asked for raw output only.

Sponsors

Details

Marketplace
gupsammy/Claudest
Source
plugins/claude-research
Category
Community

More from gupsammy/Claudest

All 8