Hey HN, I built repo-guide to make it easier to dive into and contribute to unfamiliar codebases. You can see an example of what it generates here: https://wolfmanstout.github.io/repo-guide/

Unlike most AI documentation tools that focus on Q&A, repo-guide generates comprehensive, browsable guides. It's designed to complement (not replace) human-authored documentation, with full transparency about AI generation.

Why?

* Deepening expertise: One of the best ways to advance as an engineer is to learn how libraries and systems you use are built under the hood. Many AI tools emphasize Q&A chat, which is great if you already know what questions to ask, but not as helpful when you’re trying to discover new details. By generating detailed, navigable guides, repo-guide helps surface interesting design choices you might otherwise miss.

* Onboarding contributors: If you’re new to a repo, figuring out directory layouts and dev tools can be a slog. A comprehensive auto-generated guide lets you ramp up faster.

How It Works:

* You install it via pip install repo-guide, then run repo-guide <path_to_repo>.

* It uses a bottom-up approach that examines each directory and file, generating Markdown docs you can browse locally (or deploy).

* Under the hood, it leverages Simon Willison’s LLM package (https://github.com/simonw/llm) to call LLM APIs (e.g., Gemini 2.0 Flash by default -- you can specify another model via --model).

* The system prompt encourages verbosity so you’ll see thorough coverage of internals (you can customize or shorten this via --custom-instructions).

What’s Next?

* Future ideas include a live chatbot that references both the generated docs and code, plus auto-generated changelogs.

* This is one of my weekend projects, so maintenance might be sporadic, but I’m happy to take feedback and suggestions!

Submissions

Show HN: Repo-guide – AI-generated docs for codebase exploration and onboarding

comments