Discover all relevant GitHub repositories for a given topic through systematic, diverse search hypotheses executed via gh CLI and web search.
Trigger boundary
Use when: searching for GitHub repos by topic, technology, or need
Do NOT use when: evaluating known repos for quality (use run-github-repo-evaluate instead)
Workflow
Phase 1: Generate Search Hypotheses (NO subagents)
Before touching gh, THINK about search diversity. Generate a MAXIMUM of 20 search hypotheses. Each hypothesis is a different ANGLE, not a keyword synonym.
Hypothesis angles to consider:
| Angle | Example for "WebAssembly table processing" |
|---|---|
| Direct name | "webassembly table" OR "wasm table" |
| Curated lists | awesome-wasm OR awesome-webassembly |
| Language variants | "wasm" language:Rust, "wasm" language:C++ |
| Framework combos | "wasm" "react", "wasm" "vue" |
| Use-case variants | "wasm data grid", "wasm spreadsheet" |
| Known orgs | org:aspect-build, org:nicolo-ribaudo |
| Alt terminology | "WASM" vs "WebAssembly" vs "wasm-bindgen" |
| Compound OR | termA OR termB OR termC (single terms only, NOT quoted phrases) |
| README search | "topic" in:readme stars:>10 for repos with different names |
| Topic tags | --topic=webassembly |
| Broad sweep | "mcp server" --sort=stars --limit=100 then filter by description |
| Generic category | Search the broader CATEGORY, not just the specific product |
| Known org/author | --owner=BeehiveInnovations or user:torvalds |
| Plugin/skill packages | "claude plugin" OR "claude code plugin" multi-model — not all tools are MCP servers |
| Former/renamed projects | "zen mcp", "claude-flow" — repos change names |
CEILING RULES:
- Maximum 20 hypotheses total
- Maximum 5 per angle type
- STOP generating when new hypotheses would return >=80% duplicates of existing results
- Shorter, broader queries find more.
"codex mcp"finds 20 results."mcp server codex cli tool"finds 0. - For niche topics, 7-10 productive hypotheses often exhaust the space. Don't pad to 20.
CRITICAL: OR operator rules (P0 — wrong usage returns 0 results):
- OR works as BARE terms with no outer quotes:
gh search repos codex OR claude OR gemini— WORKS - OR INSIDE a quoted string FAILS:
gh search repos "codex OR claude"→ 0 results - OR between QUOTED PHRASES FAILS:
"codex bridge" OR "codex wrapper"→ 0 results - Rule: NEVER put OR inside quotes. Always bare:
gh search repos termA OR termB --sort=stars - For multi-word concepts, run SEPARATE searches: one for "codex bridge", another for "codex wrapper"
- When a hypothesis returns 0, try: unquoting, dropping terms, or splitting into multiple searches
Anti-patterns (from real testing):
- Multi-word exact phrases return 0:
"mcp server codex cli"→ 0 results - OR between quoted phrases returns 0:
"codex bridge" OR "codex wrapper"→ 0 results (see above) --topic=Xis too broad — finds megarepos tangentially relatedin:readmeis noisy — addstars:>10to suppress megarepos:"topic" in:readme stars:>10--sort=updatedsurfaces forks and junk — always use--sort=stars
Read references/search-hypothesis-thinking.md for worked examples.
Phase 2: Execute Searches (max 100 gh API calls)
For each hypothesis, run gh search repos with token-efficient output:
Standard search command:
gh search repos "QUERY" --limit 30 --sort=stars \
--json fullName,stargazersCount,description,language,updatedAt \
--jq '.[] | [.fullName, (.stargazersCount|tostring), .language // "?", (.updatedAt[:10]), (.description // "" | .[:60])] | @tsv'
Quick enumeration (when you just need names):
gh search repos "QUERY" --limit 30 --sort=stars \
--json fullName,stargazersCount \
--jq '.[] | "\(.fullName) \(.stargazersCount)★"'
EXECUTION RULES:
- Maximum 100 total
gh search reposcalls across ALL hypotheses - Pace: max 10 searches per 2 minutes to avoid GitHub API throttling
- Always
--sort=stars(never--sort=updated) - Always
--json ... --jq ...(never raw JSON — 7x token bloat) - Track which hypothesis found which repo
- If a hypothesis returns 0 results: try unquoting phrases, splitting OR terms, or broadening. Don't just skip — 0 results usually means bad syntax, not no repos.
MANDATORY: Broad sweep hypotheses (always include 2-3): Search the broad CATEGORY sorted by stars, then filter by description keywords. Run 2-3 sweeps with DIFFERENT category terms — a single sweep misses repos in adjacent categories:
gh search repos "BROAD_TERM_1" --sort=stars --limit=100 \
--json fullName,stargazersCount,description \
--jq '.[] | select(.description // "" | test("KEYWORD1|KEYWORD2";"i")) | "\(.fullName) \(.stargazersCount)★ \(.description // "" | .[:60])"'
Example for "self-hosted Notion alternative": sweep 1 = "block editor", sweep 2 = "self-hosted notes", sweep 3 = "collaborative wiki". Each catches different repos.
For product-replacement searches (finding alternatives to X): the "known product names" hypothesis often outperforms ALL other angles. Prioritize it — search each known competitor by name individually.
Supplement with web search (max 5 web searches):
- Always append
site:github.comfor repo discovery - Try Reddit:
"topic" github site:reddit.comfor community-validated picks - Use web search tools available in your environment
- Web search indexes README content better than
gh search repos— use it as a backstop
Read references/gh-search-syntax-cheatsheet.md for qualifier reference.
Read references/output-format-recipes.md for jq patterns.
Phase 3: Deduplicate, Rank & Output
- Merge all results. Deduplicate by repo fullName (case-insensitive)
- Sort by stars descending
- CEILING: Report a maximum of 50 candidates. If >50 found, cut at 50th by stars. Note total found count.
Output format — markdown table:
| # | Repo | Stars | Lang | Updated | Description |
|---|------|-------|------|---------|-------------|
| 1 | owner/name | 1234 | TS | 2026-03 | Short desc... |
Separate collections from implementations: If results include curated lists (awesome-X), meta-repos, or settings repos, list them in a separate "Collections/Meta" section below the main table. Only rank actual tool implementations in the primary table.
After the table, provide:
- Total found: N unique repos across M searches
- Search effectiveness: Which hypotheses found the most unique results
- Categories: Group repos into 3-5 natural categories if patterns emerge
Decision rules
- If topic is well-known (React, Docker): fewer hypotheses (8-12), focus on sub-niches
- If topic is niche: more hypotheses (15-20), broader OR queries
- If <5 results after all hypotheses: the topic may not exist on GitHub. Say so honestly.
- If user provides example repos: use those to reverse-engineer better search terms (check their topics, description keywords, README content)
Reference routing
| File | Read when |
|---|---|
references/search-hypothesis-thinking.md |
Starting Phase 1 — generating hypotheses |
references/gh-search-syntax-cheatsheet.md |
Building search queries — qualifier reference |
references/output-format-recipes.md |
Formatting gh output — jq patterns |
references/search-diversity-examples.md |
Need more angle inspiration for a specific domain |
references/web-search-patterns.md |
Supplementing gh search with web search |
references/dedup-and-rank.md |
Merging results from multiple searches |