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.