repo-map walks a repository, sends each eligible file to an OpenRouter model, and writes the results as a tree to <repository>_repo_map.md. Analyses are cached in SQLite, so the next run only re-sends files that changed.

Each file gets a description, the one thing a contributor is most likely to get wrong, a maintenance flag, an architectural role, its critical dependencies, and a refactoring suggestion or security note when one applies. An entry from examples/example.md, which is repo-map run on itself:

├── main.py (Python)
│   ├── Description: Console-script entrypoint for repo-map. run_main() configures logging, imports RepoMapApp lazily, runs RepoMapApp().run() under asyncio.run, and maps failures to exit codes: 1 for configuration errors and unexpected exceptions, 130 for Ctrl-C.
│   ├── Developer Consideration: The RepoMapApp import inside run_main() is deliberate: importing cli_handler builds the settings singleton and rate limiter, and a ValueError there (e.g. bad API_SEMAPHORE_LIMIT) must be caught after setup_logging(). Moving it to module scope breaks that handling.
│   ├── Maintenance Flag: Stable
│   ├── Architectural Role: Entrypoint
│   ├── Critical Dependencies:
│   ├──   - repo_map.logging_utils: setup_logging() configures logging before any application code or errors run.
│   └──   - repo_map.cli_handler: Supplies RepoMapApp, the application whose async run() does all the work.

Getting started

Set an OpenRouter API key, then run repo-map with uv, no install step needed:

export OPENROUTER_API_KEY=sk-or-...
uvx repo-map /path/to/repository

To keep it installed instead:

uv tool install repo-map
repo-map /path/to/repository

Requires Python 3.12 or newer. repo-map asks for confirmation before it sends anything; -y skips the prompt.

Configuration

Settings come from the environment, or from a .env file in the directory you run repo-map from. .env.example lists them all.

Usage

repo-map /path/to/repository [-y] [--model MODEL] [--concurrency N]

A run writes three files into the target repository. Add them to its ignore rules if you don't want them committed.

A cached analysis is reused while the file's SHA-256 hash, the model, and repo-map's analysis contract all still match. Editing a file, switching --model, or upgrading to a release with a revised prompt triggers re-analysis. Each run prunes entries for files it no longer finds, and the cache stays valid when the repository is renamed or cloned elsewhere.

What gets sent

Each request carries the repository's file and directory names, short descriptions of the files the target imports or shares a directory with, and the full text of the target file. Review the repository and its ignore rules before approving a run, and don't analyze secrets or source you aren't authorized to share with OpenRouter.

A file's source is sent only if it is a regular file (symlinks are never followed) in a supported text format, at most 64 KiB, valid UTF-8, and free of NUL bytes. Binary and media formats are never sent.

repo-map skips these paths by default, then applies the target's root .gitignore. An excluded directory is not traversed, so nothing inside it is read or sent.

Matching follows gitignore's last-match-wins rule, so a negation in the target's .gitignore, such as !app.conf, brings an excluded file back. Only the root .gitignore is read.

Project structure

Development

git clone https://github.com/cyanheads/repo-map.git
cd repo-map
uv sync
make check

• make check is the gate: Ruff lint and format check, pyright, pytest, uv lock --check, and the changelog index check. The changelog step runs under Bun.
• A change to the prompt or the response fields bumps ANALYSIS_CONTRACT_VERSION in src/repo_map/llm_service.py, so cached analyses made under the old contract are redone.
• CHANGELOG.md is generated: add changelog/<major.minor>.x/<version>.md, then run make changelog.
• CLAUDE.md has the full set of working rules.

Contributing

Bugs and feature requests go through the issue forms; CONTRIBUTING.md covers what makes one actionable. Report vulnerabilities privately as described in SECURITY.md.

License

Apache-2.0. See LICENSE.