Git Stars Agent helps you turn your starred GitHub repositories into practical project recommendations.

This version uses Pydantic AI with Gemini through the google-gla:gemini-2.5-flash model. The core GitHub tools are still plain Python functions, so they can be tested or reused without the chat agent.

What It Can Do

• Fetch a user's starred repositories from GitHub.
• Extract useful search terms from a project description.
• Keyword-search stars by name, description, language, and topics.
• Rank starred repositories against the current project.
• Fetch and summarize repository READMEs for deeper inspection.
• Keep a conversational terminal session so you can ask follow-up questions.

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Set the Google/Gemini API keys in .env (based on .env.example):

export GOOGLE_API_KEY="your_google_api_key_here"
export GEMINI_API_KEY="your_gemini_key_here"
export GOOGLE_GENAI_USE_VERTEXAI="0"

GitHub settings:

export GITHUB_USERNAME="your_github_username_here"
export GITHUB_TOKEN="your_github_token_here"

GITHUB_TOKEN is optional for public stars, but it gives higher rate limits and allows authenticated GitHub API access.

Agent + max # of repos settings:

export GITSTARS_MODEL="google-gla:gemini-2.5-flash"
export GITSTARS_MAX_REPOS="300"
export GITSTARS_LOGFIRE="0"

Run

python cli.py --username your-github-username

Then ask things like:

I am building a Python voice AI agent with realtime audio, FastAPI, and a React dashboard.
Which of my starred repos are useful?

For deeper inspection:

Look at the READMEs for the top 3 candidates and tell me which one is most practical to use first.

For language-specific searches, the agent asks GitHub for each repository's language breakdown instead of relying only on the primary language field. Increase GITSTARS_MAX_REPOS or pass --max-repos if relevant repositories are older in your starred list.