repomap

<div align="center">

# repomap

<!-- oneliner -->**A map of your codebase for AI agents: code graph, search, call paths and change impact. No API key.**<!-- /oneliner -->

Code graph · hybrid search · call paths · change impact · an interactive graph UI.<br>
One Rust binary. Local. No API key. MIT.

[![npm](https://img.shields.io/npm/v/@sylphx/repomap?color=8aa4ff&label=npm)](https://www.npmjs.com/package/@sylphx/repomap)
[![CI](https://github.com/SylphxAI/repomap/actions/workflows/ci.yml/badge.svg)](https://github.com/SylphxAI/repomap/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.SylphxAI%2Frepomap-42d6a4)](https://registry.modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/license-MIT-ffb454)](LICENSE)
<!-- repomap:agent-ready -->[![agent-ready 93/100](https://mark.sylphx.com/badge/agent--ready-93%2F100-brightgreen)](https://github.com/SylphxAI/repomap#agent-readiness-score)<!-- /repomap:agent-ready -->

[**Live demo**](https://sylphxai.github.io/repomap/demo) · [Docs](https://sylphxai.github.io/repomap/) · [Quickstart](#quickstart) · [Tools](#what-your-agent-gets) · [Graph UI](#the-graph-ui) · [Benchmarks](https://sylphxai.github.io/repomap/benchmarks) · [Compare](#how-it-compares)

<img src="docs/public/img/demo.gif" alt="repomap demo: the map of excalidraw, searching restoreElements, its code and callers, then the impact of changing it" width="100%">

<sub>The real UI on excalidraw (687 files, indexed in under half a second): search, a symbol's code and callers, then the blast radius of a change. <a href="https://sylphxai.github.io/repomap/demo">Try it in your browser</a>, no install needed.</sub>

</div>

## Quickstart

```bash
npx -y @sylphx/repomap setup     # add repomap to Claude Code, Codex, Cursor, VS Code, Claude Desktop, Windsurf, Gemini CLI
npx -y @sylphx/repomap serve     # open the graph UI for the current repo
```

That's it. Add `--claude-hooks` to also [enrich Claude Code's Grep and Glob](#claude-code-hook). `setup` detects the clients you have, writes their MCP config, and prints every change it made. Run it again and nothing changes. Then ask your agent: *"Use repomap to map this repo."*

<details>
<summary>Manual MCP config</summary>

```json
{
  "mcpServers": {
    "repomap": { "command": "npx", "args": ["-y", "@sylphx/repomap", "mcp"] }
  }
}
```

Claude Code: `claude mcp add repomap -- npx -y @sylphx/repomap mcp`
Claude Desktop, one click: download `repomap-<version>.mcpb` from the [latest release](https://github.com/SylphxAI/repomap/releases/latest), open it, and pick your project folder.
Claude Code plugin: `/plugin marketplace add SylphxAI/repomap`, then `/plugin install repomap@repomap`
Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.repomap]
command = "npx"
args = ["-y", "@sylphx/repomap", "mcp"]
```

Docker (stdio, amd64/arm64):

```json
{ "mcpServers": { "repomap": { "command": "docker", "args": ["run", "-i", "--rm", "-v", "/path/to/repo:/workspace:ro", "ghcr.io/sylphxai/repomap"] } } }
```

The server indexes the client's workspace root (or its working directory, or `REPOMAP_ROOT`). Every tool also takes `root`.
</details>

## Why

Agents burn most of their context on `grep`, `ls` and reading whole files just to work out where things are. repomap gives them the map up front:

- **Where is it?** Hybrid search that matches symbol names, the words inside functions *and* what the code means, with the lines that matched. Ask "where are failed requests retried" or `parseConfig`.
- **What is this?** One call returns a symbol's code, callers with call-site lines, callees, subtypes and the tests that reach it.
- **How does A reach B?** The shortest call path, each hop cited `file:line`.
- **What breaks if I change this?** Direct and indirect callers, importing files, modules touched, tests to run, and a risk level. Point it at your `git diff` before you commit.
- **What does this repo look like?** Modules found from real dependencies (not just folders), the most central files, the most used symbols, and entry points.

All of it comes from a local index: tree-sitter parsing, a resolved import and call graph, PageRank, Louvain communities, BM25 over AST chunks, and a small static code embedding model (33 MB, downloaded once from Hugging Face, then offline). Nothing leaves your machine, and no API is called.

## What your agent gets

<!-- tools:start (generated by `repomap tools`; CI checks it) -->
Six tools, each with an obvious job:

| Tool | Ask it | Returns |
|---|---|---|
| `map` | "Give me the lay of the land" / `focus: "src/server"` | Modules, central files, key symbols, entry points; an outline with line numbers when focused |
| `search` | `"where are failed requests retried"`, `"parseConfig"` | Ranked `file:line` ranges (functions, methods, classes) by keywords, names and meaning, with the matching lines |
| `context` | `SessionStore.refresh`, `src/auth/token.ts`, `token.ts:42` | Code, callers (with call sites), callees, subtypes, members, imports, importers, tests |
| `trace` | `from: handleRequest, to: db.query` | Shortest call path, or the call tree above/below a symbol |
| `impact` | `target: verifyToken` or `changed: true` | Risk level, callers by depth, importing files, modules, tests to run |
| `db` | `table: users`, or `url_env: DATABASE_URL` for a live database | Tables, keys, indexes, and the code (`file:line`) that queries each table |
<!-- tools:end -->

Answers are compact text that cites `file:line`, so they cost few tokens. Pass `format: "json"` for structured output.

```text
> impact target=decode

# Impact (LOW risk)
Changing: function decode (src/auth/token.ts:14)
1 direct caller, 3 symbols affected in total across 3 files and 2 modules; 1 file importing the changed files; no tests reach this.

## Direct callers (will break if the contract changes)
- function verifyToken — src/auth/token.ts:8

## Indirect (depth 2)
- method SessionStore.refresh — src/auth/session.ts:5

## Indirect (depth 3)
- function handleRefresh — src/api/router.ts:6

## Importing files
- src/auth/session.ts
```

The same commands work in your terminal: `repomap map`, `repomap search "…"`, `repomap context X`, `repomap trace A B`, `repomap impact --changed`, `repomap db`.

## The graph UI

```bash
npx -y @sylphx/repomap serve            # live, with code preview
npx -y @sylphx/repomap export           # repomap.html: one self-contained file you can publish
```

<table>
<tr>
<td width="50%"><img src="docs/public/img/impact-tokio.webp" alt="Impact view on tokio: dependents of runtime/task/mod.rs highlighted by depth"></td>
<td width="50%"><img src="docs/public/img/code-panel-tokio.webp" alt="Code panel on tokio: harness.rs poll() with its callers and callees"></td>
</tr>
<tr>
<td><b>Impact.</b> Select a file and press <kbd>i</kbd>: everything that depends on it lights up by depth, with a list you can click through.</td>
<td><b>Code.</b> Click a symbol to see its source, callers and callees. <b>Open ↗</b> jumps to your editor or to GitHub.</td>
</tr>
</table>

- WebGL rendering (Sigma.js) that stays smooth with tens of thousands of files and edges
- Modules coloured and clustered by their real dependencies, file size by PageRank; tests, examples and docs are muted and one click away
- <kbd>/</kbd> searches files, symbols and code; <kbd>d</kbd> shows dependencies; <kbd>f</kbd> fits the view
- Click a module to focus it, <kbd>Shift</kbd>-click to hide it; toggle tests, edges and labels
- `export` writes one HTML file with deep links (`#path/to/file`) and GitHub links pinned to your commit. It's a good fit for a README, a wiki or a design review.

## Database map

```bash
npx -y @sylphx/repomap db                              # from migrations / Prisma / Drizzle / SQLAlchemy / Diesel
npx -y @sylphx/repomap db --url-env DATABASE_URL       # live Postgres, MySQL or SQLite, read-only
npx -y @sylphx/repomap db users                        # one table: columns, indexes, who references it, where it is queried
npx -y @sylphx/repomap db --serve                      # the same graph UI, for tables and foreign keys
```

repomap reads your schema from the repository: SQL migrations (applied in order, with `down` migrations skipped), `schema.prisma`, Drizzle `pgTable`/`mysqlTable`/`sqliteTable`, SQLAlchemy and Flask-SQLAlchemy models, and Diesel `table!`. It can also introspect a live database. Each table is linked to the code that queries it: raw SQL (`FROM users`), Prisma (`prisma.user.findMany`), Diesel (`users::table`), and ORM models or tables used by files that import them.

<img src="docs/public/img/db-crates-io.webp" alt="repomap db --serve on crates.io: 39 tables, 78 foreign keys, 527 code references" width="100%">

Live connections are strictly read-only:
- **Postgres** runs in a `READ ONLY` transaction that the server must confirm.
- **MySQL** runs in a `START TRANSACTION READ ONLY` transaction.
- **SQLite** is opened read-only with `query_only`.

Only catalog metadata is read, never table rows. The connection string comes from an argument or an environment variable, and it is never stored or printed. Agents get the same data through the `db` MCP tool; pass `url_env` rather than the URL itself.

## Agent-readiness score

```bash
npx -y @sylphx/repomap score
```

The score rates how well an AI agent can work in the repository, from 0 to 100. It covers eight checks:
- agent instructions (AGENTS.md / CLAUDE.md and how useful they are)
- discoverable build and test commands
- test coverage
- CI
- module boundaries
- file sizes
- docs
- types

Each check that falls short comes with a concrete fix, and the score ends with a badge line for your README. For CI, use `--min 70`; `--update-readme README.md` refreshes the badge.

Keep the badge fresh with the GitHub Action:

```yaml
# .github/workflows/agent-ready.yml
on: { push: { branches: [main] } }
permissions: { contents: write }
jobs:
  score:
    runs-on: ubuntu-latest
    s