repo-map scans a repository, extracts structural metadata, and asks an OpenRouter model to document eligible files. It writes a Markdown tree at the repository root and stores results in SQLite so unchanged files do not need another API call.

Features

• Markdown and console repository trees
• Python AST extraction plus lightweight Java, JavaScript, TypeScript, and C# structure parsing
• Structured descriptions, developer considerations, maintenance flags, dependency notes, architectural roles, refactoring suggestions, and security assessments
• Root .gitignore support plus built-in exclusions for caches, dependencies, build output, and repo-map artifacts
• Symlink-safe traversal that does not follow linked files or directories
• SHA-256-based SQLite cache for unchanged files

See examples/example.md for a full sample report.

Install

Install the published CLI with uv:

uv tool install repo-map

For development, clone the repository and install its Poetry environment:

git clone https://github.com/cyanheads/repo-map.git
cd repo-map
poetry install

repo-map requires Python 3.12 or newer.

Configure

Set an OpenRouter API key in the environment or a project-root .env file:

export OPENROUTER_API_KEY=your_api_key_here

Optional environment variables:

repo-map sends repository paths, languages, imports, symbols, and existing descriptions to OpenRouter. Review the target repository and its ignore rules before approving a run. Do not analyze secrets or source you are not authorized to disclose.

Use

With the published tool installed:

repo-map /path/to/repository

From a source checkout:

poetry run repo-map /path/to/repository

Options:

Examples:

poetry run repo-map /path/to/repository --model anthropic/claude-sonnet-4.6
poetry run repo-map /path/to/repository --concurrency 3 -y

Each run creates these files inside the target repository:

• <repository>_repo_map.md: generated Markdown report
• .repo-map-cache.db: source hashes and cached LLM metadata
• .repo_map_structure.json: pre-enhancement structural data

Add them to the target repository's ignore rules if needed. Delete .repo-map-cache.db to force a complete reprocessing pass.

How it works

1. Load built-in exclusions and the target repository's root .gitignore.
2. Walk the directory tree and extract supported structural metadata.
3. Compare file hashes with the SQLite cache.
4. Request structured JSON metadata from OpenRouter for eligible changed files.
5. Update the cache and write the console, JSON, and Markdown outputs.

Development

Run the local gate and build both distribution artifacts before submitting a change:

poetry run python scripts.py check
poetry build

Focused commands:

poetry run python scripts.py format
poetry run python scripts.py lint
poetry run python scripts.py test
poetry run python scripts.py list-skills

Project workflows live under skills/. Bugs and feature requests use the forms on the issues page.

License

Apache-2.0. See LICENSE.