repo-guide 0.4.1

Uses AI to help understand repositories and their changes.

repo-guide

Use AI to generate guides to code repositories.

NEO: Can you fly that thing?
TRINITY: Not yet. Tank, I need a pilot program for a military B-212 helicopter. Hurry!
[seconds later ...]
TRINITY: Let's go.

— The Matrix (1999)

You can see the output of repo-guide on its own repository at https://wolfmanstout.github.io/repo-guide/. This is automatically generated and published after every release.

NOTE: The guides generated by repo-guide are intended to be complementary to human-authored documentation, not replacements.

Installation

Install this tool using pip, pipx, or uv tool install, e.g.:

pip install repo-guide

By default it uses Gemini Flash as the AI model, which requires an API key. You can either set the LLM_GEMINI_KEY environment variable or install Simon Willison's LLM command-line tool and use llm keys set gemini to store your key in a configuration file.

Usage

This tool currently only supports Git repositories and their subdirectories, with some additional features for GitHub repositories (e.g. links to files).

Typical usage:

git clone <github_url> my_repo
cd my_repo
repo-guide .

This will generate a Markdown guide in the generated_docs directory within my_repo, then run a private MkDocs server at localhost:8000 to serve the docs. It will show a progress bar as it generates docs, including how many tokens the model has used (combining input + output). You can start viewing the docs immediately, and the page will automatically reload as new docs are generated.

If you kill the server and need to restart it later, by default it will reuse any previously-generated Markdown files, so you can simply rerun the same command. You can also add --no-resume to delete and regenerate the files, or --no-gen to explicitly disable doc generation (e.g. even if a new directory has been added).

Here are some of the most common flags you may want to use:

• --output-dir: Change where the generated docs are written.
• -v or --verbose: Prints details on doc generation progress instead of a progress bar.
• --model: Sets the LLM model to use. As of 1/1/2025, the default is Gemini 1.5 Flash, which costs under a dollar for 10 million tokens and has a 1 million token context window, making it a great fit. You can try other Gemini models such as gemini-2.0-flash-exp, or OpenAI models if OPENAI_API_KEY is set, as supported by simonw/llm and simonw/llm-gemini.
• --token-budget: Sets an approximate token budget to avoid overspending. Please also consider setting limits in your account. I'm not responsible for any unexpected costs, including due to bugs in this tool.

For a full description of command line flags, run:

repo-guide --help

You can also use:

python -m repo_guide --help

Troubleshooting

If the command fails either due to an error or hitting the token budget, simply rerun the command and it will resume (unless --no-resume is applied). Most common model errors (e.g. rate-limiting) should be automatically retried with exponential backoff. You can --ignore large generated or binary files that aren't automatically filtered out. If you still hit the model token limit, try setting --files-token-limit.

LLMs are unpredictable, and the generated Markdown may contain errors and broken links. The system prompt tries to mitigate common issues, but they happen anyways. The only real fix to this will be better models, which will surely come soon.

Development

To contribute to this tool, use uv. The following command will establish the venv and run tests:

uv run pytest

To run repo-guide locally, use:

uv run repo-guide