Metadata-Version: 2.5
Name: repoguide-ai
Version: 0.3.0
Summary: Scan any codebase and generate onboarding docs automatically
Project-URL: Homepage, https://github.com/M33p5t3r/repoguide-python
Project-URL: Repository, https://github.com/M33p5t3r/repoguide-python
Project-URL: Documentation, https://github.com/M33p5t3r/repoguide-python#readme
Project-URL: Bug Tracker, https://github.com/M33p5t3r/repoguide-python/issues
Author: Abram Manaka
License-Expression: MIT
License-File: LICENSE
Keywords: ai,anthropic,cli,codebase,developer-tools,documentation,llm,mcp,ollama,onboarding,openai,repository
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: anthropic<1,>=0.40.0
Requires-Dist: mcp[cli]<2,>=1.0.0
Requires-Dist: openai<2,>=1.0.0
Provides-Extra: anthropic
Requires-Dist: anthropic<1,>=0.40.0; extra == 'anthropic'
Provides-Extra: openai
Requires-Dist: openai<2,>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# 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:**
```bash
pip install repoguide-ai
```

**From source:**
```bash
git clone https://github.com/M33p5t3r/repoguide-python.git
cd repoguide-python
pip install .
```

### 2. Run RepoGuide

**With Anthropic (default):**
```bash
$env:ANTHROPIC_API_KEY="sk-ant-..."       # Windows (PowerShell)
export ANTHROPIC_API_KEY=sk-ant-...        # Mac/Linux
repoguide
```

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

**With Ollama (local, no API key):**
```bash
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](#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:

```bash
# 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 |

```bash
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`:
```bash
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.
