🧠 RepoMind

Understand any GitHub repository with AI.

RepoMind is an AI-powered developer tool that analyzes any public GitHub repository and lets you have an evidence-based conversation with it. Paste a repository URL, and RepoMind clones it safely, understands its architecture, tech stack, APIs, and database, generates a structured report — and then answers your questions by actually searching and reading the code.

Features

• One-click repository analysis — URL in, structured report out: overview, tech stack, file structure, entry points, architecture, data flow, important files, dependencies, APIs, database, setup guide, and AI insights.
• Agent-style chat ("Ask RepoMind") — not a single LLM call. The agent decides which tools to use (search_repository, read_file, semantic_search, find_api_endpoints, ...) and answers from real evidence, citing file paths and functions.
• Semantic code retrieval — code is chunked on function/class boundaries, embedded (Gemini or any OpenAI-compatible API), and stored in a persistent ChromaDB vector store, so large repositories are searched, not dumped into the model.
• Smart filtering — ignores .git, images, binaries, lock files, generated files, and oversized files; prioritizes README → configs → entry points → core source.
• Hallucination-resistant — if the repository has no evidence for a claim, RepoMind says so instead of inventing it.
• Architecture diagram — a Mermaid diagram generated from the detected entry points, API endpoints, and database usage.
• Disk cache — analyses are cached per commit SHA; re-opening the same repository is instant.
• Safe by design — repository code is never executed, installed, or passed to a shell; only read and analyzed.

Architecture

Streamlit UI (app.py)
      │
      ▼
RepositoryAnalyzer (orchestrator)
      │  ┌──────────────────────┐
      ├──► github_client        │  URL validation, REST API metadata,
      │   └─────────────────────┘  safe shallow clone
      │  ┌──────────────────────┐
      ├──► analyzers/           │  deterministic: dependencies, entry
      │   └─────────────────────┘  points, API routes, DB code, ranking
      │  ┌──────────────────────┐
      ├──► retrieval/           │  code-aware chunker + ChromaDB store
      │   └─────────────────────┘  (embeddings)
      │  ┌──────────────────────┐
      └──► agents/              │  tool registry + ReAct-style loop
          └─────────────────────┘  (LLM function calling)

The agent loop works like this: the user question plus a system prompt ("answer only from repository evidence") is sent to the LLM along with the tool schemas. The model returns a function call, the agent executes the real tool against the local clone / vector store, feeds the result back, and repeats until the model produces a final answer (capped at 8 iterations). Tools are plain Python functions — adding a tool means adding one function and one schema entry.

Tech Stack

Screenshots

Screenshots to be added — run the app and capture the landing page, the report tabs, and the chat view.

Installation

Requires Python 3.11+ and Git on your PATH.

# 1. Clone or download this repository
git clone https://github.com/your-username/repomind.git
cd repomind

# 2. Create a virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Linux/macOS

pip install -e .

# 3. Configure environment
copy .env.example .env        # Windows
cp .env.example .env          # Linux/macOS

Terminal CLI

RepoMind also runs in your terminal (published as repomind-ai; the command is repomind):

# One-time install via uv (installs Python for you if missing)
uv tool install repomind-ai

# Analyze a repository, then chat about it interactively
repomind https://github.com/psf/requests

# Or ask a single question and exit
repomind https://github.com/psf/requests --ask "where is authentication handled?"

# Once published to npm, no-install usage works too:
npx repomind-ai https://github.com/psf/requests

On first run the CLI asks for your Gemini or OpenAI key and saves it to ~/.repomind/config.env. Override providers/models with --provider and --model.

Website

A self-hostable web app built on FastAPI. It serves the same analyzer through a job-based API and ships with a dependency-free static frontend.

# Install server extras and run locally
pip install -e ".[server]"
uvicorn server.main:app --reload
# open http://localhost:8000

API surface:

Hybrid key model: visitors without a key use the server's shared key under per-IP daily limits (REPOMIND_DAILY_ANALYZES, default 5; REPOMIND_DAILY_QUESTIONS, default 40). Pasting your own Gemini/OpenAI key in the UI bypasses the limits; keys stay in the browser session and are never persisted server-side.

Deployment

The included Dockerfile builds one container that serves the frontend, API, and worker threads (Python 3.12 slim + git).

Deploy to Render / Fly.io / Railway:

1. Push this repository to GitHub.
2. Create a Web Service from the repo — the host detects the Dockerfile (Render/Railway) or use fly launch (Fly.io).
3. Set environment variables on the host:
   • GEMINI_API_KEY (or OPENAI_API_KEY + OPENAI_BASE_URL) — the shared key
   • GITHUB_TOKEN (optional, raises GitHub API limits)
4. Deploy. The cache lives at /tmp/repomind inside the container and is disposable — a cold cache simply means the next analysis re-clones.

Continuous delivery: tagging a release (git tag v0.1.0 && git push --tags) triggers .github/workflows/publish.yml, which publishes the Python package to PyPI (trusted publishing) and the npm launcher to npmjs.com. One-time setup: add the PyPI trusted publisher for this repo (workflow publish.yml, environment pypi) and store an npm automation token as the NPM_TOKEN secret. CI (pytest on Linux/macOS/Windows × Python 3.11/3.12) runs on every push via .github/workflows/ci.yml.

Environment Variables

Note on free tiers: Gemini's free tier works reliably for chat but limits embedding requests (gemini-embedding-001, ~100 requests/min). NVIDIA's free tier authenticates and provides embeddings (nvidia/nv-embed-v1) but chat completions time out. A practical combination: Gemini for chat + NVIDIA for embeddings — set EMBEDDING_PROVIDER=openai with the NVIDIA key/base URL. OpenCode Zen (https://opencode.ai/zen/v1, sk-... key) also works as an OpenAI-compatible chat provider — e.g. OPENAI_MODEL=hy3-free (free models are rate-limited per account). The OpenAI client is also fully usable with a paid OpenAI key.

Running Locally

streamlit run app.py

Open the printed URL (default http://localhost:8501), paste a public GitHub repository URL, and click Analyze Repository.

Example Usage

1. Enter https://github.com/psf/requests
2. RepoMind clones it, builds the report (~1–3 min depending on repo size), and shows the tabs.
3. In 💬 Ask RepoMind, try:
   • "What does this project do?"
   • "Where is authentication implemented?"
   • "Explain the architecture."
   • "Which database is being used?"
   • "What files should I read first if I'm new to this project?"

Answers cite evidence, e.g.:

Authentication lives in requests/auth.py → HTTPBasicAuth.__call__(), which sets the Authorization header on each request.

If a claim cannot be supported by the repository, you'll see: "I couldn't find evidence for this in the repository."

Project Structure

├── app.py                       # Streamlit UI (desktop/local)
├── pyproject.toml               # packaging; console script `repomind`
├── Dockerfile                   # web deployment container
├── .github/workflows/           # CI (pytest) + publish (PyPI/npm)
├── repomind/
│   ├── config.py                # env vars, limits, paths
│   ├── github/github_client.py  # URL validation, API, safe clone
│   ├── analyzers/
│   │   ├── repository_analyzer.py  # orchestration, tree, ranking, mermaid
│   │   ├── dependency_analyzer.py  # manifests & tech stack
│   │   └── code_analyzer.py        # entry points, API routes, DB code
│   ├── retrieval/
│   │   ├── chunker.py           # code-aware chunking
│   │   └── vector_store.py      # ChromaDB persistence + search
│   ├── agents/repository_agent.py  # tool registry + agent loop + report
│   ├── cli/                     # terminal entry point (rich TUI)
│   ├── llm/gemini_client.py     # Gemini wrapper, retries, embeddings
│   └── utils/helpers.py         # logging, safe subprocess, file guards
├── server/
│   ├── main.py                  # FastAPI: analyze jobs, ask endpoint
│   ├── ratelimit.py             # per-IP daily limits (shared key)
│   └── static/                  # frontend (tokens.css / styles.css / app.js)
├── npm/                         # `npx repomind-ai` launcher (bootstraps uv)
├── tests/                       # pytest suite
└── docs/superpowers/specs/      # design specifications

Testing

.venv\Scripts\python -m pytest -q

Limitations

• Analyzes public repositories only (private repos are refused by design).
• Free-tier Gemini rate limits apply; a Pro model can be set via REPOMIND_CHAT_MODEL.
• Repos over 500 MB (configurable) are refused before cloning.
• Heuristic detection of API endpoints and database code covers common frameworks (FastAPI, Flask, Django, Express, Spring, etc.); exotic frameworks may be partially detected.
• Analysis time scales with repository size (bounded by REPOMIND_MAX_FILES).

Future Improvements

• GitHub PR / commit-history analysis
• Code-quality and security-vulnerability scanning
• Repository comparison and developer-onboarding mode
• Automatic documentation generation
• "Explain this code like I'm a beginner" mode
• Deeper architecture visualization (per-module diagrams)

License

MIT