repomap

An interactive map of any Python project, running entirely on your machine.

pip install repomap-viz    # or run without installing: uvx --from repomap-viz repomap serve .
repomap serve ./my-project

Your browser opens on a GitHub-style view of the project:

• Map: modules, calls and class inheritance as a graph you can pan, zoom, filter by folder, and focus on one node. Circular imports are highlighted.
• Trace: pick an entry point (a FastAPI or Flask route, a Typer or Click command, a __main__ block) and follow the calls step by step, with the code of each step.
• Overview: what's in the project, where execution starts, and which files failed to parse.
• AI summaries (optional): a 2–3 sentence explanation of any function, class or module, generated when you click it.

Privacy

• Analysis is static. Your code is parsed, never imported or run.
• The server listens on 127.0.0.1 only and refuses requests from other websites.
• Nothing is written inside your project. The summary cache lives in ~/.cache/repomap/.
• Code only leaves your machine if you turn on AI summaries, and then only the node you click Summarize on.

AI summaries

Summaries use NVIDIA's API with your own key:

export NVIDIA_API_KEY=nvapi-...
repomap serve ./my-project                          # default model: openai/gpt-oss-20b
repomap serve ./my-project --model z-ai/glm-5.3     # or any chat model NVIDIA hosts
repomap serve ./my-project --no-ai                  # never send anything

Each summary is cached by a hash of the code and the model name, so unchanged code is never sent twice.

Commands

repomap serve PATH [--port 8765] [--no-ai] [--no-browser] [--model NAME]
repomap analyze PATH -o graph.json          # just the analysis, as JSON
repomap export PATH -o report.html          # one self-contained HTML file; add --no-source to leave code out

An exported report opens offline in any browser, with no server. It includes summaries that are already cached, and the source code unless you pass --no-source. Anyone you send it to can read everything in it.

How call analysis stays honest

Python is dynamic, so a call graph built from source alone is always best-effort. repomap only draws an edge it can justify:

• exact: local functions, imported names (including __init__ re-exports), self.method(), super(), Class(...).method(), with methods looked up through base classes.
• inferred: one plausible target, e.g. a parameter annotated with a project class, or a FastAPI Depends(...).
• Everything else (getattr, callbacks, dictionary dispatch) is left out. A missing edge is better than a wrong one.

Development

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/python scripts/build_demo.py      # refresh the frontend demo data after analyzer changes

See CLAUDE.md for the architecture, the graph schema and the project rules.