search_repos

Dev-session use cases this serves well:
  • "Rust agent harness — what are my options?" — finds frameworks/harnesses ranked by literal relevance, not star count
  • "Python async rate limiter — show me existing libraries" — dedicated libs beat big frameworks
  • "What's the landscape of LLM observability tools?" — surfaces the actual category leaders
  • "Is there already a tool for managing Claude Code sessions?" — hyper-specific gem hunting, small focused CLIs float up
  • "What's new in this ecosystem this week?" — set `trending=True` for repos created in the last 7 days
  • "Disambiguate a name the user mentioned" — one-hop metadata lookup

Ranking (multi-query mode): composite relevance score combining literal description match × 3, topic-tag match × 2, cross-phrasing robustness × 2, recency bonus (0-3), and log-scaled stars at half-weight. Stars are a TIEBREAK, not a driver — this is why a 500-star literal-match repo can outrank a 40,000-star repo that doesn't contain the query terms in its description. Tested against 6 dev-session queries in benchmarks/rank_experiment.py; composite scoring produced the best top-5 on 5/6 queries and consistently surfaced small-but-quality gems that star-first ranking buried.

Query sharpness — most→least noisy:
  • `topic:X` — self-assigned tags. Noisy for umbrella terms (e.g. `topic:mcp` returns opportunistic taggers like n8n). Sharp for tight niches (`topic:ratatui`).
  • `in:readme "phrase"` — matches any mention in the README. Medium.
  • `in:description "phrase"` — matches repos whose short description contains the phrase. Sharpest, but note that GitHub does literal substring matching — so `"embeddings database"` will also match "embedded database" (burned in testing). Prefer specific, domain-meaningful phrases.

SHORTLISTING — always use `queries=[...]` with 2-4 phrasings. Single-phrase `in:description` is sharp but narrow; popular options routinely describe themselves with different wording. For example, `in:description "Postgres operator"` returns Zalando's postgres-operator (5k★) but misses CloudNativePG (8k★), which describes itself as "Kubernetes-native PostgreSQL." Passing both phrasings via `queries=` runs them in parallel, dedupes by repo, and annotates each result with `matched K/N`. Recipe for concept X in language L: `queries=['in:description "X" language:L', 'in:description "X synonym" language:L', 'topic:X-slug language:L']`.

Other tips: keep queries short (GitHub uses AND logic — more terms = fewer results). Use the `language` filter instead of putting the language in the query. Use `archived:false` to exclude abandoned repos. Use `pushed:>YYYY-MM-DD` to filter by activity. For strict popularity filtering (production dependency shortlisting), add `stars:>N` explicitly — the tool no longer applies a star floor by default because gem-finding needs to see small repos.

NOT for: searching code inside repos (use `search_code`), fetching a repo you already know by name (use `get_file`/`repo_tree`), or authoritative library popularity (check package registries via `search_packages`).

IMPORTANT: repo search does NOT support file-level qualifiers like path:, filename:, extension:, content:, symbol: — GitHub silently matches them as literal content, giving misleading results with no error. Use `search_code` for those.