How it works: queries GitHub's code-search index for files containing
the symbol name, parallel-fetches the top ~15 candidate files, parses
each with tree-sitter, and queries the AST for declaration nodes
(class, function, struct, trait, interface, etc.) whose name matches
exactly. Results are ranked with type-declaring kinds
(class/struct/trait) first, then functions, then methods, then
variables. Success responses include real absolute line numbers and
ripgrep-style context (2 lines above, match line, 5 lines below)
pulled from the full file, not GitHub's 3-line fragment.

Languages with AST-precise matching via tree-sitter: Python, JavaScript,
TypeScript, Go, Rust, Java, Ruby, C, C++. Other languages fall back to
a regex-on-fragment path that is less precise but still useful.

Best for **distinctive** symbol names — `FastMCP`, `DataLoader`,
`ClaudeAgentOptions`, `Runtime`, `Tokenizer`. These are names creators
chose to be findable, and the first-declaration-wins ranking is
almost always right.

NOT for generic names like `connect`, `handle`, `init`, `get`, `run`
that show up in every library. GitHub's text-relevance ranking puts
usage-heavy files above the one declaring them, so the declaration
file often isn't in the top 15 we fetch. For generic names, use
`search_code` with disambiguating keywords (e.g.
`search_code("export function connect", repo="reduxjs/react-redux")`)
or combine with `path:` qualifier to narrow the search.

NOT for finding call-sites or usage patterns — use `search_code`
with the symbol name and a `repo:` qualifier for that.

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.