Install

Requirements

Per track. Nothing below Track 1 needs anything Track 1 does not.

The code CLI: in VS Code, Command Palette → Shell Command: Install 'code' command in PATH.

Track 1

The engine, alone

Two binaries, nao and elevator, and nothing else. This is all you need for CLI analysis, CI checks, and giving a coding agent the graph over MCP — no UI, no editor.

The source is not published publicly yet — these commands assume you already have the checkout.

From your checkout

cd nao
cargo install --path . --force      # nao and elevator into ~/.cargo/bin

Check it works

nao analyze . -f json -o analysis.json
nao analyze . -f ascii              # or just look at it

If nao: command not found, ~/.cargo/bin is not on your $PATH.

What the engine can do →

Track 2

Add the browser visualizer

The UI is served by the binary you just installed — there is no separate thing to install, only a server to start. nao watch analyses one folder and keeps it current as you save:

nao watch . --port 3200        # one repo, live, re-analysed on save
# open http://127.0.0.1:3200

nao serve is the other shape: several already-analyzed repositories behind one API, with a picker in the UI. It is what the hosted /visualizer was baked from.

# several analyzed repos under one API, each seeded from a local path
nao serve --port 3400 \
  --seed my-org__api=/code/api \
  --seed my-org__web=/code/web

If the page loads empty

The binary serves whatever is in ui/dist. A release build has it; a fresh clone may not:

./scripts/build.sh --ui        # only if ui/dist is missing

Live versus frozen, and why it can be hosted →

Track 3

Add the VS Code extension

One script, because the extension needs both pieces below it — the binary it spawns and the UI it embeds:

The source is not published publicly yet — these commands assume you already have the checkout.

cd nao
./scripts/install.sh           # binaries + extension, one step

That builds and installs both binaries into ~/.cargo/bin/, packages the VS Code extension and installs it into your default profile. Reload VS Code and the nao icon appears in the activity bar.

• Target specific VS Code profiles: ./scripts/install.sh Work Personal
• Different editor CLI: NAO_CODE_CLI=cursor ./scripts/install.sh
• Binaries only — back to Track 1: NAO_SKIP_EXTENSION=1 ./scripts/install.sh

First run

1. Open a folder.
2. Click the nao icon in the activity bar.
3. Command Palette → Nao: Open Code Visualizer.
4. In Visual Scopes, tick the folders you want drawn.

Saves trigger a re-analysis, so the graph tracks the code as you work.

The views, the settings, what the editor adds →

Agents (MCP)

Track 1 is enough. nao mcp speaks MCP over stdio — register it with your client. For Claude Code, a .mcp.json at the project root:

{
  "mcpServers": {
    "nao": { "command": "nao", "args": ["mcp"] }
  }
}

Ten read-only tools appear. The agent loop shows the order that works.

nao CLI reference

# One-shot analysis to JSON
nao analyze ./my-project -f json -o analysis.json

# Filter by language, cap traversal depth
nao analyze ./my-project -l rust -l python -d 5

# Watch mode — re-analyses on save, serves data + SSE
nao watch ./my-project --port 3200

# MCP server over stdio, for coding agents
nao mcp

elevator CLI

Installed alongside nao by every track — it is the second binary out of the same crate.

elevator ./spec                         # full project map
elevator ./spec --focus f.protocol      # one branch, as an LLM bundle
elevator ./spec --check                 # broken refs, orphans (CI-friendly)
elevator ./spec --code-map              # path → entities; double claims
elevator ./spec --drift --code-root .   # anchors that no longer hold
elevator --docs                         # full language reference

The language guide covers the six entity kinds and the sketch-first method. elevator --docs prints the full reference offline.

Updating

git pull
./scripts/install.sh

Then Cmd+Shift+P → Developer: Reload Window. The script is safe to re-run for any change — it reinstalls both binaries and repackages the extension regardless of what you touched. On Track 1, cargo install --path . --force is the whole update.

Troubleshooting

nao: command not found / elevator: command not found

cargo install did not run, or ~/.cargo/bin is not on your $PATH.

The visualizer loads but the page is blank

ui/dist is missing. ./scripts/build.sh --ui from the checkout.

code: command not found

Install the VS Code CLI: Command Palette → Shell Command: Install 'code' command in PATH.

The extension installed but no icon appears

Reload the window — Cmd+Shift+P → Developer: Reload Window.

The extension cannot find the binary

Set nao.binaryPath to its absolute location.

The graph shows files instead of entities

The auto-level picker escalated because there are too many entities for the viewport. Pin the level to “entity” in View Options, or narrow the Visual Scopes.