# repo-guide

[![PyPI](https://img.shields.io/pypi/v/repo-guide.svg)](https://pypi.org/project/repo-guide/)
[![Changelog](https://img.shields.io/github/v/release/wolfmanstout/repo-guide?include_prereleases&label=changelog)](https://github.com/wolfmanstout/repo-guide/releases)
[![Tests](https://github.com/wolfmanstout/repo-guide/actions/workflows/test.yml/badge.svg)](https://github.com/wolfmanstout/repo-guide/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/wolfmanstout/repo-guide/blob/master/LICENSE)

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

```bash
pip install repo-guide
```

By default it uses Gemini Flash as the AI model, which [requires an API
key](https://ai.google.dev/gemini-api/docs/api-key). You can either set the
`LLM_GEMINI_KEY` environment variable or [install Simon Willison's
LLM command-line tool](https://llm.datasette.io/) and use [`llm keys set
gemini`](https://llm.datasette.io/en/stable/setup.html#saving-and-using-stored-keys)
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](https://www.mkdocs.org/) 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](https://github.com/simonw/llm) and
  [simonw/llm-gemini](https://github.com/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:

```bash
repo-guide --help
```

You can also use:

```bash
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](https://docs.astral.sh/uv/). The following
command will establish the venv and run tests:

```bash
uv run pytest
```

To run repo-guide locally, use:

```bash
uv run repo-guide
```
