RepoGuide

A CLI tool that scans any local codebase and generates a detailed onboarding document — the kind of walkthrough a senior dev would write for a new team member, produced automatically.

Works with Anthropic (Claude), OpenAI (GPT), or Ollama (local models, no API key needed).

---

What This Demonstrates

Business problem solved: Onboarding to a new codebase is slow. Architecture lives in someone's head, entry points aren't obvious, and setup instructions are outdated or missing. RepoGuide reads the repo and produces a structured markdown guide covering architecture, tech stack, entry points, key patterns, setup instructions, and areas of complexity.

Why this matters for AI engineering: This is AI applied to a real developer workflow — not a chatbot demo. It demonstrates MCP tool orchestration, structured LLM output generation, a provider abstraction that makes the LLM swappable, and a two-pass analysis strategy that keeps token usage efficient by scanning first and reading selectively.

---

How It Works

RepoGuide uses a two-pass architecture:

Pass 1 — Structural scan (no LLM, no tokens spent): An MCP server scans the directory tree, detects the tech stack from config files (package.json, requirements.txt, Cargo.toml, etc.), counts file types, and identifies likely entry points based on framework-specific knowledge.

Pass 2 — Selective deep read (targeted, token-efficient): Based on what Pass 1 found, the agent reads only the files that matter — entry points, config files, READMEs. The LLM receives the full tree structure plus contents of key files, not the entire codebase.

Generation: Everything gathered is sent to the configured LLM provider with a structured system prompt. Before generating, RepoGuide prints an approximate input-token estimate; in interactive mode it asks you to confirm before spending on the call. The output is a markdown document — by default an ONBOARDING.md, or a purpose-specific document when you pick a --template — written in a direct, specific tone with actual file names, function references, and code patterns.

---

Quick Start

1. Install

From PyPI:

pip install repoguide-ai

From source:

git clone https://github.com/M33p5t3r/repoguide-python.git
cd repoguide-python
pip install .

2. Run RepoGuide

With Anthropic (default):

$env:ANTHROPIC_API_KEY="sk-ant-..."       # Windows (PowerShell)
export ANTHROPIC_API_KEY=sk-ant-...        # Mac/Linux
repoguide

With OpenAI:

$env:OPENAI_API_KEY="sk-..."               # Windows (PowerShell)
export OPENAI_API_KEY=sk-...               # Mac/Linux
repoguide --provider openai

With Ollama (local, no API key):

ollama pull llama3.1                      # Download a model first
repoguide --provider ollama
repoguide --provider ollama --model mistral   # Use a different model

3. Follow the Prompts

You'll be asked for:

• Repository path — absolute path to any local repo
• Ignore patterns — optional comma-separated folder names to skip

RepoGuide scans the repo, shows what it detected, asks you to confirm, then generates and saves ONBOARDING.md in the target repo's root.

---

Non-Interactive Usage

Every prompt can be replaced with a flag, so RepoGuide can run headlessly — in a script, a CI job, or a one-liner.

Flag	Purpose
--path <dir>	Point at a repository without the interactive path prompt.
--ignore <a,b,c>	Comma-separated folders to skip, instead of the ignore prompt.
--output <file>	Output filename. Defaults to a name derived from the template.
--template <name>	Document purpose — see Templates below.
--yes / --non-interactive	Auto-accept stack detection and skip the generation confirmation.
--version	Print the installed version and exit.

Combine --path with --yes to run with no prompts at all:

# Fully headless: scan, generate, and save with no interaction
repoguide --path ./my-project --yes

# Skip build folders and write to a custom filename
repoguide --path ./my-project --ignore node_modules,dist --output DOCS.md --yes

The input-token estimate still prints under --yes, but generation proceeds without waiting for confirmation. --yes without --path exits with a clear message rather than hanging on the path prompt.

---

Templates

RepoGuide can produce different documents from the same repository, depending on what you need to understand. Pick one with --template; the default is an onboarding guide.

Template	Produces	Default filename	Best for
default	Onboarding guide — overview, tech stack, architecture, setup, complexity	ONBOARDING.md	Getting a new developer productive
architecture	System design — components, data & control flow, patterns, risk	ARCHITECTURE.md	Understanding structure before changing it
api	Interface reference — public surface, inputs/outputs, usage, errors	API.md	Consuming a library or service
security	Security review — attack surface, auth, input handling, secrets	SECURITY.md	Assessing risk and attack surface

repoguide --path ./my-project --template architecture
repoguide --path ./my-project --template security --yes

When --output is omitted, the filename derives from the template (shown above) so the document's name matches its purpose. Passing --output explicitly always overrides this.

---

Architecture

┌─────────────────────────────────────────────────────┐
│                  CLI (cli.py)                        │
│                                                     │
│  1. Get repo path from user                         │
│  2. Connect to MCP server                           │
│  3. Call scan_repo → display detected stack          │
│  4. Confirm with user                               │
│  5. Call detect_entry_points → get reading list      │
│  6. Call read_file on each entry point               │
│  7. Send to LLM with chosen template → markdown      │
│  8. Save {template}.md to the target repo            │
└────────────┬──────────────────────┬─────────────────┘
             │ MCP Protocol         │ LLM Call
             ▼                      ▼
┌────────────────────────┐  ┌──────────────────────────┐
│  MCP Server            │  │  Provider (providers.py)  │
│  (repo_server.py)      │  │                          │
│                        │  │  AnthropicProvider       │
│  scan_repo             │  │  OpenAIProvider          │
│  read_file             │  │  OllamaProvider          │
│  detect_entry_points   │  │                          │
└────────────────────────┘  └──────────────────────────┘

MCP Server Tools

Tool	Purpose	Token Cost
scan_repo	Walk directory tree, detect stack from config files, count file types	Zero (pure Python)
read_file	Read a specific file with max line guard	Proportional to file size
detect_entry_points	Suggest key files based on detected frameworks, falling back to package.json (main/scripts) for framework-less Node projects	Zero (pure Python)

LLM Providers

Provider	Command	API Key Required	Best For
Anthropic	--provider anthropic	Yes (ANTHROPIC_API_KEY)	Best output quality (default)
OpenAI	--provider openai	Yes (OPENAI_API_KEY)	Alternative cloud provider
Ollama	--provider ollama	No	Offline use, privacy, free

Override the default model with --model:

repoguide --provider anthropic --model claude-opus-4-6
repoguide --provider openai --model gpt-4o-mini
repoguide --provider ollama --model codellama

Supported Frameworks

The stack detection recognizes: Next.js, React, Vue, Nuxt, SvelteKit, Express, NestJS, FastAPI, Flask, Django, Streamlit, Astro, Remix, Gatsby, and generic Node/Python projects. Adding a new framework means adding entries to the detection maps — no logic changes needed.

---

Example Output

Run RepoGuide against any local repo to generate a full document in the repo's root. With the default template that's an ONBOARDING.md covering architecture, tech stack, entry points, key patterns, setup instructions, and areas of complexity. Other templates reshape the analysis toward a specific purpose — system design (architecture), interface reference (api), or security review (security) — each written in a direct, specific tone with actual file names and function references.

---

Adding a New Provider

1. Create a class in providers.py that inherits from LLMProvider
2. Implement generate(system_prompt, user_message, max_tokens) -> str
3. Implement validate_config() -> str | None
4. Add it to the PROVIDERS dict

The MCP server, scanning logic, and output format are all provider-agnostic.

---

Design Principles

RepoGuide uses the MCP client/server pattern (FastMCP framework) applied to a developer tooling problem. The provider abstraction demonstrates clean separation between orchestration logic and model calls — the LLM is a swappable component, not the product.