🤖 Code Assistant

An AI-powered repository analysis CLI that clones any GitHub repo, scans every file, and produces a structured quality report — documentation scores, code quality scores, maintainability scores, tech stack detection, and categorized insights with severity levels. Supports OpenAI or fully-local Ollama inference.

How it works

GitHub URL ──► Clone repo ──► Scan & classify files ──► LLM analysis ──► Structured report
                                                                              │
                                                            ┌─────────────────┼──────────────┐
                                                            │                 │              │
                                                      Quality scores    Insights       Recommendations
                                                      (doc/code/maint)  (bug/perf/arch)  (prioritized)

What it produces

The analyzer outputs a RepositoryAnalysis with:

• Quality scores — documentation_score, code_quality_score, maintainability_score (0–1 float each)
• Technology stack detection — languages, frameworks, libraries, tools, databases — auto-detected from repo contents
• Categorized insights — each CodeInsight has a category (bug, improvement, architecture, performance), severity (low → critical), file path, line number, description, and actionable suggestion
• Trending comparisons — benchmarks the repo against current industry trends
• Prioritized recommendations — ordered list of what to fix first

Example

python main.py https://github.com/some-org/some-repo --provider ollama

🎯 Repository Analysis Results

Summary:
  Well-structured FastAPI application with clean separation of concerns...

┌──────────────── Technology Stack ────────────────┐
│ Category     │ Technologies                      │
├──────────────┼───────────────────────────────────┤
│ Languages    │ Python, SQL                       │
│ Frameworks   │ FastAPI, SQLAlchemy               │
│ Libraries    │ Pydantic, httpx, pytest           │
│ Tools        │ Docker, uv, ruff                  │
└──────────────┴───────────────────────────────────┘

┌──────────────── Quality Scores ──────────────────┐
│ Metric          │ Score                           │
├─────────────────┼─────────────────────────────────┤
│ Documentation   │ 0.72                            │
│ Code Quality    │ 0.85                            │
│ Maintainability │ 0.78                            │
└─────────────────┴─────────────────────────────────┘

Key Insights:
  1. [HIGH] Missing input validation on user-facing endpoints
     💡 Add Pydantic request models with field constraints

  2. [MEDIUM] No error handling in database connection layer
     💡 Wrap connection logic in try/except with retry backoff

Stack

Component	Technology
Language	Python 3.12+
CLI	Typer + Rich (tables, colored output)
LLM (cloud)	OpenAI API
LLM (local)	Ollama (run fully offline)
GitHub	Clone + REST API for metadata
Typing	Pydantic v2 — all I/O typed (RepositoryAnalysis, CodeInsight, TechnologyStack)

File classification

Every file is classified before analysis:

FileType	What it covers
source_code	.py, .js, .ts, .java, etc.
documentation	.md, .rst, .txt
configuration	.toml, .yaml, .json, .env
test	test_*.py, *_test.go, etc.
asset	Images, fonts, binaries

Only files under max_file_size (configurable) are sent to the LLM. Large repos are handled gracefully.

Setup

pip install -r requirements.txt

# Configure in config/settings.py:
#   - github_token (for private repos)
#   - llm_provider: "openai" or "ollama"
#   - OpenAI API key or Ollama endpoint

python main.py <github-repo-url>
python main.py <github-repo-url> --provider ollama  # local inference

License

MIT