| name | search-repos |
| description | Search GitHub for repositories matching a topic or keyword using the gh CLI, rank by stars and maintenance signals, and return a shortlist of candidates. Use when the user asks whether a tool already exists for a given purpose, or wants an overview of popular projects in a space. |
Search GitHub Repos
Help the user discover existing GitHub projects that address a stated need, so they can evaluate whether to use, fork, or integrate one instead of building from scratch.
When to use
Trigger phrases include:
- "Is there already a tool/library/CLI/plugin for X?"
- "Search GitHub for Y"
- "What are the top projects for Z?"
- "Before I build this, check if it already exists"
Procedure
1. Clarify the query if needed
Ask the user at most one short clarifying question only if the target is genuinely ambiguous. Otherwise translate their request into search terms directly.
2. Run the search
Use gh search repos with sensible defaults. Start broad, then narrow if results are too noisy.
gh search repos "<keywords>" \
--sort stars \
--limit 20 \
--json name,owner,description,stargazersCount,updatedAt,language,license,url,openIssuesCount,pushedAt
Use --language=<lang> when the user specified a language. Use topic filters (--topic=<topic>) when a canonical topic tag applies (e.g. --topic=cli, --topic=mcp).
For richer queries (e.g. combining topic with minimum stars), use gh api:
gh api -X GET search/repositories \
-f q='<keywords> stars:>100 pushed:>2025-01-01' \
-f sort=stars -f order=desc --jq '.items[] | {name, full_name: .full_name, stars: .stargazers_count, pushed: .pushed_at, language, license: .license.spdx_id, open_issues: .open_issues_count, description, url: .html_url}'
3. Rank and filter
From the returned set, build a shortlist of the top 5–10 candidates. For each candidate, capture:
- Full name (
owner/repo)
- Stars
- Last push date (convert to "N months ago" for readability)
- Open issues
- License (flag missing/unclear licenses)
- Primary language
- One-sentence description
Drop candidates that are obviously off-topic (wrong language, archive/mirror, gist-style one-liners) unless the user explicitly wants all results.
4. Present results
Output a compact table or list, ordered by stars, but call out any candidates that look abandoned (last push > 12 months ago) with a ⚠️ marker. Offer the user a next step: dive deeper on a specific candidate (hand off to evaluate-candidates), broaden/narrow the search, or document findings to planning/ (hand off to document-findings).
5. Keep the exact query
Preserve the exact gh command you ran. If the user later asks to document the findings, that query must be recorded alongside the research date so results are reproducible.
Guidance
- Stars are a rough signal, not the whole story. A 500-star repo updated last week often beats a 10k-star repo abandoned in 2022.
- Archived repos (
--archived=false by default on newer gh) should be excluded unless the user wants historical context.
- Forks with more stars than the upstream sometimes indicate the project has moved — note this.
- Do not invent repository names. Only report what the CLI actually returned.
