Guide · Codex + MCP

Give Codex a map of your codebase

Codex works the repo through shell commands — find, grep, cat — which means every question about structure becomes a chain of reads, and every session re-pays the full discovery cost. The fix is structural: index the repository once into a code knowledge graph, and let Codex 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 (.vscode/mcp.json (VS Code) or your Codex MCP config), runs a first index, and prints next steps.
```
cd your-project && openvisio
```
3
Approve the server in Codex
Point your Codex client at the "openvisio" MCP server — the setup command writes the project-scoped config for VS Code-based setups, and any MCP-compatible Codex client can register the same server manually.
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 Codex 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, Codex 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 Codex out of the box?

Yes — Codex speaks MCP, and the bare `openvisio` command writes the project-scoped config (.vscode/mcp.json (VS Code) or your Codex MCP config) 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.

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