repo2graph

<!--
  @authormark v1 -- do not remove (authorship watermark)⁠​‌‌‌​​​​​‌‌‌​‌​‌​‌‌‌​​​‌​‌​‌​​​​​​‌‌​​​​​​‌‌​​‌​​‌​​‌​​‌​‌​‌​‌​‌​‌‌‌​‌‌​​‌‌​​‌​‌​‌‌‌​‌​​​‌‌‌​​​‌​‌‌‌​‌‌‌​‌‌​​​‌‌​​‌‌​‌​‌​‌​​‌‌‌​​‌‌‌​​‌‌​‌​​​​‌‌​​‌‌​‌‌​​‌‌​​​​‌​‌‌‌‌​​​​​‌‌‌​​‌⁠
  Copyright (c) 2026 Srinivasan Vijayaraghavan <srinivasan.shyam2000@gmail.com>
  Author: https://github.com/Srinivasan-78
  SPDX-License-Identifier: MIT
  Fingerprint: AMK1.puqP02IUvetqwc5NsC6ax9
-->
# repo2graph

<!-- mcp-name: io.github.Srinivasan-78/repo2graph -->

repo2graph reads a folder full of code and draws you a map of it — then uses that map to answer
questions about the code, with citations. Agents can ask it questions directly over MCP.

![The whole map of a project: 300 dots and the arrows between them](docs/images/graph-overview.png)

*One project, drawn by `repo2graph`. Each dot is a folder, file, function or library. Each arrow is
a real connection found in the code.*

## The idea

Imagine you get handed a big box of Lego that someone else already built things with. You want to
know what connects to what. You could look at every brick one at a time, or someone could hand you
a map.

Code is like that box. A project has hundreds of files, and the files use each other in ways you
cannot see by looking at one file at a time.

repo2graph makes the map. On the map:

- Every **thing** is a dot. A folder is a dot. A file is a dot. A function (a small named piece of
  code that does a job) is a dot. We call these dots **nodes**.
- Every **connection** is an arrow. "This file is inside that folder." "This function uses that
  function." "This file borrows code from that library." We call these arrows **edges**.

Dots joined by arrows are called a **graph**. That is the whole idea.

## Why a map helps

If you search a project for the word "login", you get every file that happens to say "login",
including comments and typos.

The map is better, because it knows which function actually does the login work, and it also knows
which functions call it and which functions it calls. So you get the real answer plus its
neighbours.

That matters most when a chatbot or AI helper is reading the code for you. Giving it the right
piece of code plus the pieces around it is usually what it was missing.

## How it works, in three steps

```mermaid
flowchart LR
    A[your code] --> B[tree-sitter<br/>reads the code]
    B --> C[graph<br/>dots + arrows]
    C --> D[graph.html<br/>the picture]
    C --> E[overview.md<br/>the words]
    C --> F[chunks.jsonl<br/>pieces for an AI]
    C --> G[graph.graphml / graph.cypher<br/>other tools, Neo4j]
```

1. **It reads the code.** It uses tree-sitter, the same tool code editors use to colour your code.
   So it understands real code structure instead of guessing from words. It needs no setup and
   works on a project it has never seen.
2. **It builds the map.** Folders, files, functions, classes and imports become dots. "contains",
   "defines", "calls", "imports", "inherits" become arrows.
3. **It cuts the code into small pieces.** Roughly one piece per function or class. Each piece gets
   a few lines at the top saying who calls this function, what it calls, and what its description
   says. Those little pieces are what you feed to an AI when you want it to answer questions about
   the code.

No graph library is involved: degree counting, layout and GraphML generation are pure Python, with
no NetworkX.

## Install

You need Python 3.10 or newer.

```bash
pip install repo2graph
```

Two optional extras, neither needed for the core:

```bash
pip install "repo2graph[rag]"   # sentence-transformers + numpy, for meaning-based search
pip install "repo2graph[mcp]"   # the MCP SDK, for serving the map to an agent
```

To run it without installing anything — which is how most people wire up the MCP server — use
[uv](https://docs.astral.sh/uv/):

```bash
uvx repo2graph build . -o .r2g
uvx --from "repo2graph[mcp]" repo2graph-mcp /path/to/project
```

Or from a checkout, if you want to change it:

```bash
git clone https://github.com/Srinivasan-78/repo2graph
cd repo2graph
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

## Use it

### 1. Make the map

```bash
repo2graph build /path/to/your/project -o .r2g --git-history 200
```

That is it. It walks the project, reads it, and puts everything in a folder called `.r2g`. A medium
project takes seconds. A very big one takes a minute or two.

`--git-history 200` is optional. It looks at the last 200 saves (commits) in the project's history
and adds links between files that keep getting changed together. Those links are a good clue about
which files secretly depend on each other.

No copy on your machine? Point it at GitHub instead — it downloads, maps, and tidies up after
itself:

```bash
repo2graph github psf/requests -o out/requests --git-history 200
```

### 2. Look at the map

```bash
open .r2g/human/graph.html   # the picture
cat .r2g/human/overview.md   # the same thing written out in words
repo2graph stats -o .r2g     # how many dots, arrows and functions there are
```

`graph.html` is one single file. No internet needed, nothing to install. Open it in a browser and
you get the picture: drag to move around, scroll to zoom, drag a dot to pin it in place, click a
dot to see what that function looks like and everything it is connected to.

Zoom in and every dot is named, so you can read the real call paths:

![Zoomed into the map: named functions, files and libraries joined by arrows](docs/images/graph-zoom.png)

The side panel counts what is on screen and lets you switch each kind of dot and arrow on or off:

![Side panel with search box, node kinds and relationship kinds, each with a count](docs/images/graph-sidebar.png)

By default the picture shows the 300 busiest dots, and hides calls that go out to other people's
code, because those triple the number of arrows and tell you little about your own project. Tick
`external` and `CALLS_EXTERNAL` in the side panel to show them. Want a simpler picture? Redraw it
with fewer dots: `repo2graph map -o .r2g --viz-nodes 80`.

### 3. Ask it questions

A search tool and a GraphRAG context packer are built in. Neither needs an AI account.

```bash
repo2graph query "how does routing match a path" -o .r2g       # find the code
repo2graph rag "how does the pack stay inside its budget" -o .r2g   # pack it for an LLM
```

`query` finds the best matching pieces and follows the arrows one step out, so the functions around
each answer come along too. `rag` does the same and then assembles a budget-bounded markdown pack,
repo map on top, every block stamped with an exact citation header:

```
### [cite: repo2graph/cli.py:22-28] `parse_formats` (CALLS out of cmd_build)
# file: repo2graph/cli.py
# function: parse_formats  (lines 22-28, python)
# called by: repo2graph/cli.py::cmd_build, repo2graph/cli.py::cmd_github
def parse_formats(spec: str) -> set[str]:
...
```

The `(CALLS out of cmd_build)` part is the *reason* the block is in the pack: either `seed` (the
search found it) or the arrow that dragged it in.

Word matching misses code that says the same thing in different words, so you can add meaning-based
search on top — vectors are computed once, then blended into every ranking:

```bash
repo2graph embed -o .r2g                        # needs the [rag] extra
repo2graph rag "how is a request routed" -o .r2g --vectors
```

`repo2graph rag --answer` will also send the pack to an LLM and stream back a grounded answer. It is
the one command that puts your source code on the network — read
[the warning](docs/cli.md#-answer-sends-your-code-to-someone-elses-computer) first.

**Full flag tables, budget accounting and how retrieval works: [docs/cli.md](docs/cli.md).**

### 4. Hand the map to an agent over MCP

`repo2graph-mcp` is a stdio [MCP](https://modelcontextprotocol.io) server, so an agent can ask the
map questions itself instead of you pasting a pack into a chat window.

Point it at a project and it serves it. Nothing to install and no setup step: if no map exists yet,
the first question builds one and answers from it.

```bash
claude mcp add repo2graph -- uvx --from "repo2graph[mcp]" repo2graph-mcp /path/to/project
```

For Claude Desktop, Cursor and generic clients, the JSON block is the same four lines:

```json
{
  "mcpServers": {
    "repo2graph": {
      "command": "uvx",
      "args": ["--from", "repo2graph[mcp]", "repo2graph-mcp", "/path/to/project"]
    }
  }
}
```

Three tools, deliberately:

| Tool | Arguments | What comes back |
|---|---|---|
| `repo_map` | none | Languages, hub files and top entry points. Stable across calls, so it caches. |
| `repo_search` | `query`, optional `k`, `hops`, `budget_tokens` | Seed chunks plus their graph neighbours, each headed `[cite: path:start-end]`. |
| `repo_neighbours` | `node_id`, optional `hops`, `limit` | One graph hop from a symbol: callers, callees, base classes, defining file. The thing grep cannot do. |

The server keeps three promises the CLI leaves to you: secrets are **always** excluded, output is
hard-capped at 12 000 tokens and re-measured before it is returned, and `k`/`hops` are clamped so no
single call can wedge the event loop every client shares. It never calls an LLM itself.

Auto-build writes only what the tools read, and only into a directory you pointed it at. Build ahead
with `repo2graph build` if you want the first question to be fast or want the picture too, and pass
`--no-auto-build` to require an index that already exists.

**Client configs, which directory gets indexed, and the full contract: [docs/mcp.md](docs/mcp.md).**

### 5. Or run it in CI

repo2graph is on the GitHub Marketplace, so a fresh map can live next to your code:

```yaml
- uses: actions/checkout@v4
  with: { fetch-depth: 0 }   # full history, so CO_CHANGE edges are meaningful
- uses: Srinivasan-78/repo2graph@v1
  with:
    path: .
    git-history: "500"
    artifact-name: repo-graph
```

**All inputs and outputs: [docs/gi