Vesalius

When you ask an AI coding assistant about your project, something like "what breaks if I change this?", it works the way a new teammate would on their first day: search for a name, open a file, search again, open another file, and slowly piece the answer together. Every one of those steps costs time and tokens, and on a real codebase they add up fast. Vesalius gives your assistant a map instead. It reads your repository once, right on your Mac, and remembers how everything connects: which file uses which, who calls what, where a feature actually lives. Then Claude Code can ask it directly and get answers with exact file and line references, usually in one call instead of a chain of searches. In our benchmark that cut the tokens Claude Code spent answering real questions about real codebases roughly in half, and a blind AI judge scored the answers about the same. A map is useful to people too, so Vesalius also comes as a Mac app and a VS Code extension for exploring code yourself. Vesalius itself never uploads your code.

Where it helps

• Before a risky change. "What breaks if I rename this?" lists the callers, including type-inferred uses a text search would miss, the files to edit and the tests to run, with a check on how complete that list is.
• In a codebase you didn't write, or wrote a year ago. See its shape, its health, its hotspots and where to start, before reading a single file.
• When an agent does the digging. Claude Code asks Vesalius first and greps far less, so it spends fewer tokens and fewer turns getting to an answer of about the same quality.
• When you want the code to stay healthy. A health score with every deduction explained, dependency cycles, oversized files, possibly unused code, each with its evidence.

Quick start

You need: a Mac with Apple silicon that runs Xcode 26 (Vesalius targets macOS 15 and later; we test on macOS 27 with Xcode 26.6 and Swift 6.3), and git. For the agent part, Claude Code. For the editor part, VS Code 1.95 or later and Node 22 or later.

1. Build and install the vesalius command

git clone https://github.com/haplollc/Vesalius.git
cd Vesalius
scripts/install-cli.sh        # builds a release binary and installs it to ~/.local/bin
vesalius --version            # 2.0.0

The first build downloads SwiftSyntax and ArgumentParser (about 47 MB) and compiles SwiftSyntax in release mode, so it takes several minutes: about 6 on an M2 in our runs, more on a busy machine. If ~/.local/bin is not on your PATH, the script prints the line to add to your shell profile. To install somewhere else, pass a folder: scripts/install-cli.sh ~/bin.

2. Index a project

cd ~/code/your-app
vesalius index

Here is Vesalius indexing its own repository:

Indexed ~/code/Vesalius
  files: 248 scanned · +248 added · ~0 changed · -0 removed · 0 unchanged
  graph: 9,157 symbols · 79,037 references · 2,611 dependency edges
  time:  5.97s · index ~/Library/Application Support/Vesalius/Indexes/vesalius-…/index.v4.sqlite

After that, every query re-reads only the files that changed (a refresh with nothing changed took 0.1 to 0.25 s in our runs). You can also skip this step: the first question from Claude Code builds the index on its own.

3. Connect Claude Code

claude mcp add --scope user vesalius -- vesalius mcp

That one line works in every project. Claude Code tells the server which folder it is working in, and Vesalius serves that repository, indexing it the first time it is asked. Check it with claude mcp list:

vesalius: vesalius mcp - ✔ Connected

# Each of these replaces the registration from step 3, so remove that one first:
claude mcp remove --scope user vesalius

# Share it with your team through .mcp.json. Each person approves it once when they next start Claude Code;
# until then `claude mcp list` shows "⏸ Pending approval".
claude mcp add --scope project vesalius -- vesalius mcp

# If Claude Code cannot find `vesalius` on its PATH, give the full path
claude mcp add --scope user vesalius -- ~/.local/bin/vesalius mcp

# Always serve one repository, wherever Claude Code is started
claude mcp add --scope user vesalius -- vesalius mcp --repo ~/code/your-app

# Load every Vesalius tool on demand instead of two up front (see VESALIUS_MCP_PROFILE under Configuration)
claude mcp add --scope user vesalius -e VESALIUS_MCP_PROFILE=lean -- vesalius mcp

Any other MCP client that speaks stdio can run vesalius mcp --repo /path/to/repo. The Mac app's Settings › Agents can register Vesalius with Claude Code and Codex for you, and copies an mcpServers JSON block for other clients; add "--repo", "/path/to/repo" to its args unless your client starts servers in the project folder.

4. Ask

Ask Claude Code the way you normally would. It picks the right tool on its own:

Who calls SessionStore.save, and what would I have to update if I renamed it? Where are in-app purchases handled? Are there any circular imports under src/? What's in PaymentService.swift?

Most answers come back in one call (long ones in pages), with file:line evidence, and usages, feature_map and dependency_cycles also say how complete they are. Claude still opens or greps files when it wants to check something, just far less: in our benchmark, 2.65 search, read and shell calls per question instead of 7.2.

The five tools Claude gets

usages and feature_map are loaded up front, which adds about 900 tokens to Claude Code's context in every session where Vesalius is registered (cached after the first request, and already counted in the benchmark totals). The other three wait behind Claude Code's tool search until they are needed. Every tool is read-only.

This is exactly what Claude sees, because the command line prints the same text as the MCP tool:

$ vesalius usages RepositoryEngine.ensureFresh
@discardableResult public func RepositoryEngine.ensureFresh(options:progress:) async throw…  VesaliusKit/Sources/QueryEngine/RepositoryEngine.swift:201-210 · method · target QueryEngine
2 callers in 2 files (VesaliusCommands 1 · VesaliusMCP 1) · complete: "ensureFresh" occurs 9×: 2 resolved to the target, 1 declaration, 2 strings (DebugCommands.swift:21,76), 4 non-source (README.md); 0 unresolved
RepositoryEngine (owner type) is used by 56 other files
VesaliusKit/Sources/VesaliusCommands/VesaliusCommand.swift
  func GlobalOptions.engine() :70-81  "Opens the engine and brings the index up to date unless --no-refresh."
    77 │ if let summary = try await engine.ensureFresh(progress: { printer.update($0) })
    called by: runTool(_:_:full:) :95 · Watch.run() :254 · DebugCompleteness.run() DebugCommands.swift:31 · +22
VesaliusKit/Sources/