GitHub Repo Analyzer

A structured Python application that analyzes a public GitHub repository using deterministic metrics plus an LLM provider.

Supported LLM providers:

• Ollama (local)
• Gemini API

It analyzes:

• stars, forks, watchers, open issues
• primary/core language and language percentages
• README quality
• selected source code
• repository structure and health signals
• detected project stack
• AI-generated summary and recommendations

1. Requirements

• Python 3.10+
• Git
• A GitHub personal access token (recommended for higher API rate limits)
• Either:
  • Ollama installed and running locally, or
  • a Gemini API key

2. Create a virtual environment

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Windows cmd

python -m venv .venv
.venv\Scripts\activate

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

python -m pip install --upgrade pip
pip install -r requirements.txt

4. Configure credentials

Copy the example environment file:

Windows

copy .env.example .env

macOS / Linux

cp .env.example .env

Edit .env.

For Ollama:

LLM_PROVIDER=ollama
GITHUB_TOKEN=your_github_token
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5-coder:7b

For Gemini:

LLM_PROVIDER=gemini
GITHUB_TOKEN=your_github_token
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-2.5-flash

Do not commit .env.

5. Ollama setup

Install Ollama, then pull the model configured in .env, for example:

ollama pull qwen2.5-coder:7b

Ensure Ollama is running before starting the analyzer.

6. Run

Interactive:

python app.py

Or:

python app.py https://github.com/owner/repository

Choose a provider for one run:

python app.py https://github.com/owner/repository --provider ollama

or:

python app.py https://github.com/owner/repository --provider gemini

Save the normalized report:

python app.py https://github.com/owner/repository --json report.json

7. Tests

python -m unittest discover -s tests -v

Project structure

github-repo-analyzer/
├── app.py
├── config.py
├── requirements.txt
├── .env.example
├── .gitignore
├── github/
│   ├── client.py
│   └── file_fetcher.py
├── analyzers/
│   ├── language_analyzer.py
│   ├── readme_analyzer.py
│   ├── code_analyzer.py
│   ├── structure_analyzer.py
│   └── health_analyzer.py
├── llm/
│   ├── base.py
│   ├── factory.py
│   ├── ollama_client.py
│   ├── gemini_client.py
│   ├── prompts.py
│   └── parsing.py
├── models/
│   └── repository_report.py
├── services/
│   └── analysis_service.py
├── output/
│   ├── console_reporter.py
│   └── json_reporter.py
├── utils/
│   └── github_url.py
└── tests/

How analysis works

1. Parse the GitHub URL.
2. Fetch repository metadata, languages, README, and the repository tree.
3. Select a limited number of useful source/config files.
4. Calculate deterministic language and repository-health metrics.
5. Send README and selected code to the configured LLM.
6. Normalize everything into one report.
7. Print the report and optionally write JSON.

The analyzer intentionally does not send the entire repository to the LLM. Generated/vendor/binary files and common dependency/build directories are ignored, and source input is capped.

Security

• Keep .env private.
• Use least-privilege GitHub credentials.
• Repository code is untrusted input. This project reads code but does not execute it.
• With Ollama, prompts stay with your configured local Ollama server.
• With Gemini, selected repository content is sent to the Gemini API. Do not analyze private/sensitive repositories unless that is acceptable for your environment.

Extending the project

Good next additions:

• commit/contributor activity
• stale repository detection
• dependency vulnerability tooling
• AST-based complexity metrics
• test-framework detection
• GitHub Actions analysis
• repository comparison
• web dashboard using FastAPI/Streamlit
• HTML/PDF report export