Guide · Claude Code + MCP

Give Claude Code a map of your codebase

Claude Code is a superb reasoner handed a terrible interface to your repo: ls, grep, and file reads. On a codebase of any size it spends the first minutes — and tens of thousands of tokens — just discovering which files matter. The fix is structural: index the repository once into a code knowledge graph, and let Claude Code query it over MCP — it pulls the exact neighborhood a task touches instead of reading everything.

Setup — two commands

1
Install the CLI
One global install gives you the indexer, the MCP server, and the local viewer.
```
npm install -g openvisio
```
2
Set up the repo
Run the bare command inside your project. It writes the project-scoped MCP config (.mcp.json), runs a first index, and prints next steps.
```
cd your-project && openvisio
```
3
Approve the server in Claude Code
Open Claude Code in the project folder. It detects the project-scoped .mcp.json and asks once to approve the "openvisio" server; from then on the graph tools are available in every session.
4
Watch it work (optional)
Run the viewer with spotlight on, and every file the agent queries lights up on a live 3D map of the repo, in real time.
```
openvisio view
```

What Claude Code can ask the graph

Once connected, the agent has six structured queries instead of blind file reads: resolve_context (a task-ranked skeleton plus the relevant neighborhoods, every line with a path:line anchor), find_symbol, get_dependents, get_neighborhood, get_hotspots, and get_repo_skeleton. Discovery stops being a token sink and becomes a lookup.

Your code stays on your machine

Indexing is deterministic — tree-sitter parses the repository into files, symbols, imports, and calls, and PageRank ranks what matters. No LLM ever sees your code during indexing, nothing is uploaded, and the whole thing runs on your machine.

What it saves

Exploring an unfamiliar repository routinely burns 50,000+ tokens before any real work begins, and most agents re-send every opened file on every turn. With the graph, Claude Code asks "what does this task touch?" and reads only the answer — in practice 30–90× fewer tokens on discovery-heavy tasks. The long-form math is in our token-cost guide.

Frequently asked questions

Does OpenVisio work with Claude Code out of the box?

Yes — Claude Code speaks MCP, and the bare `openvisio` command writes the project-scoped config (.mcp.json) for you. Approve the server once and the tools appear in the agent's toolkit.

Does indexing send my code anywhere?

No. Indexing is deterministic tree-sitter parsing on your machine — no LLM, no network. The MCP server serves the graph locally.

How is this different from letting the agent grep?

Grep finds text; the graph knows structure. "Who imports this file", "what is the ranked skeleton of this repo", and "what neighborhood does this task touch" are one query each against the pre-computed graph — with grep they are dozens of reads, re-paid every session.

Does this replace CLAUDE.md?

They complement each other. CLAUDE.md carries conventions and instructions; the graph carries live structure. Instructions tell the agent how to behave — the graph tells it where things are.

See it on your repo

Paste a GitHub URL or open a folder — the map builds in your browser in seconds.

Try it free

or npm install -g openvisio for the MCP server