repo-lens

Scan once. Query fast. Save tokens.

AI-powered repository documentation generator using local Ollama models. Builds a structured Markdown knowledge base from your codebase, then uses it to answer questions — reading only the files that matter instead of the entire repo.

What's New

• --brief mode — instant structural overview from file names alone (no code reading)
• --deep mode — thorough analysis with pattern detection, data flow, and API docs
• Smart module splitting — auto-detects logical boundaries (no more 127-file mega-docs)
• _index.md — master reference linking all docs with a file→module lookup table
• Better default model — qwen2.5-coder:7b instead of llama3.2 for real code understanding
• Curated model registry — repo-lens models --recommended shows best options
• Stronger prompts — extracts patterns, exports, dependencies, data flow with actual code references

Setup

cd repo-lens
npm install
npm link
repo-lens setup

Setup auto-installs Ollama if missing, starts the server, and pulls the default model.

Usage

# Quick structural overview (fast, no code reading)
repo-lens scan --brief

# Full deep documentation (reads all source files)
repo-lens scan --deep

# Query the knowledge base
repo-lens query "how does the auth middleware work?"
repo-lens query "where is the database schema defined?" --deep

Commands

repo-lens setup

One-command first-time setup. Installs Ollama, starts it, pulls a model.

repo-lens scan [dir]

| Flag | Description | |------|-------------| | -b, --brief | Quick overview from structure only | | -d, --deep | Full code analysis (default) | | -m, --model | Model to use (default: qwen2.5-coder:7b) | | -o, --output | Output dir (default: .repo-lens) | | --exclude | Comma-separated glob patterns | | --concurrency | Parallel LLM calls (default: 2) |

repo-lens query <question>

| Flag | Description | |------|-------------| | --deep | Also read pinpointed source files | | -m, --model | Model to use | | -d, --docs | Docs directory |

repo-lens models

| Flag | Description | |------|-------------| | -l, --list | List installed models | | -p, --pull <name> | Pull a model | | -r, --recommended | Show curated model list |

Generated Output

.repo-lens/
├── _index.md          # Master reference with file→module lookup
├── info.md            # Project overview, tech stack, entry points
├── architecture.md    # Architecture patterns, data flow, design decisions
├── manifest.json      # Machine-readable index for query pinpointing
└── modules/
    ├── src_auth.md    # Per-module: purpose, API, patterns, data flow
    ├── src_chat.md
    ├── src_products.md
    └── ...

Token Savings

| Approach | Tokens per query | |----------|-----------------| | Feed entire repo | 100K–500K+ | | repo-lens query (docs only) | 5K–15K | | repo-lens query --deep | 10K–30K |

Project Structure

repo-lens/
├── bin/cli.js                  # CLI entry point + command registration
├── src/
│   ├── index.js                # Public API exports
│   ├── cli/                    # Command handlers
│   │   ├── setup.js            # First-time setup
│   │   ├── models.js           # Model management
│   │   ├── scan.js             # Scan orchestration
│   │   └── query.js            # Query execution
│   ├── core/                   # Infrastructure
│   │   ├── config.js           # All defaults, model registry, tuning knobs
│   │   ├── ollama.js           # Ollama HTTP client
│   │   ├── ollamaSetup.js      # Auto-install, detect, start Ollama
│   │   └── scanner.js          # File system scanner + adaptive grouping
│   ├── generators/             # Doc generation + query engine
│   │   ├── docsGenerator.js    # Brief + deep doc generation
│   │   └── queryEngine.js      # Query execution + file pinpointing
│   ├── templates/              # LLM prompt templates
│   │   └── prompts.js          # All prompts (brief, deep, query, pinpoint)
│   └── utils/
│       └── helpers.js          # Shared utilities
└── package.json

Contributing

| Want to... | Where to look | |-----------|---------------| | Add a CLI command | src/cli/ → register in bin/cli.js | | Improve doc quality | src/templates/prompts.js | | Add a scan mode | src/generators/docsGenerator.js | | Support new file types | src/core/config.js → CODE_EXTENSIONS | | Add a model | src/core/config.js → MODEL_REGISTRY | | Change defaults | src/core/config.js → SCAN_DEFAULTS |

License

MIT