The graph follows your cursor
Move through a file and the selection moves with you — the entity under the caret is the entity highlighted, with its neighbourhood drawn around it. Turn it off with nao.autoVisualize when you want the view to stay put.
Component 3 of 3 · the editor
The same graph, wired to your cursor.
The thinnest of the three. It does not parse anything and it does not draw anything: it spawns the engine over your open folder and embeds the visualizer as a webview. What it contributes is the part that only an editor can — knowing where your caret is, and being able to put it somewhere else.
not on the Marketplace yet — installed from a checkout by the install script
Why a third piece exists
Five things that need an editor.
Everything else the extension shows, the browser UI already shows. This is the list that justifies installing it — and, read the other way, the list of what you give up by staying in a tab.
A node is a jump
Click one and the file opens at the line. The graph stops being a diagram of the code and becomes a way of moving through it.
Save is the refresh
The extension runs nao watch over the open folder, so the graph tracks the code as you edit rather than as you remember to re-run something.
Diff two commits
A structural diff over git worktrees — what entities and edges changed between two revisions, not what lines did. It needs a checkout on disk, which is why this one is local-only.
Native scope trees
Folders and files as a real VS Code tree with checkboxes, in the activity bar, next to the explorer you already use.
How it is put together
A webview and a child process.
On activation the extension starts nao watch on the workspace folder, at nao.serverPort. The webview is the visualizer build, talking to that server
over the same six endpoints it would use in a browser — plus a message channel to the
extension host for the two things HTTP cannot do: report where the cursor is, and ask for
a file to be opened.
There is no second renderer and no fork. The webview bundle and the browser bundle come
out of the same ui/ sources, which is why a fix to the graph shows up in
both.
Two build outputs, one source: webview-dist/ for the extension, ui/dist/ for the standalone browser UI.
Activity bar
| View | What it holds | Kind |
|---|---|---|
| Visual Scopes | Native tree with checkboxes — which folders and files get drawn. | tree |
| Analysis Scope | What gets analyzed, separately from what gets drawn. Can follow the active editor. | tree |
| Controls | Aggregation level, tree depth and density, label toggles, zoom. | webview |
| Diff | Structural comparison between two commits. | webview |
| Inspector | Kind, location, metrics and source for the selection, plus Go to Source. | webview |
| Description | The Elevator spec entry covering the selected entity, when one exists. | webview |
| Quality | Every entity ranked by metric, with smell badges. | webview |
| Educator | Good-practice lessons matched against the code, with in-editor hovers. | webview |
| Educator Problems | Those matches as a list. | tree |
The webview rows are the visualizer's own panels, hosted in the sidebar instead of in a tab. The two trees are native, because a checkbox tree is one thing VS Code does better than anything you would draw yourself.
Commands
- Nao: Open Code Visualizer — The full panel.
- Nao: Visualize Current File — A compact view around the file and entity at the cursor.
- Nao: Stop Server / Restart Server — Control the watch process by hand when it needs it.
- Nao: Select Git Repository… — Point the diff and history views at the right checkout.
Configuration
Seven settings, and defaults that work.
| Setting | Does | Default |
|---|---|---|
| nao.binaryPath | Path to the nao binary. Empty means look for it on $PATH. | empty |
| nao.serverPort | Port for the watch server the extension spawns. | 3200 |
| nao.includeTests | Include test files in the analysis. | false |
| nao.language | Restrict analysis to one language. Empty analyses everything detected. | empty |
| nao.autoVisualize | Update the visualization when you switch file. | true |
| nao.analysisScopeFollowMode | Granularity of Follow Active Editor — file or folder. | folder |
| nao.educator.hoverEnabled | Educator content in the editor hover, for Java source. | true |
The extension needs the nao binary on your $PATH, or nao.binaryPath pointing at it. That is the whole contract between components 3
and 1.
Getting it
One script, because it installs all three.
The extension cannot be installed alone — it needs the binary it spawns and the UI it
embeds. ./scripts/install.sh builds the binaries into ~/.cargo/bin, packages the .vsix and installs it into your
default profile. Reload the window and the icon appears.
- Named profiles:
./scripts/install.sh Work Personal - A different editor CLI:
NAO_CODE_CLI=cursor ./scripts/install.sh - Skip the extension entirely:
NAO_SKIP_EXTENSION=1 …
The source is not published publicly yet — these commands assume you already have the checkout.
cd nao
./scripts/install.sh # binaries + extension, one step# from vscode-extension/
npm run install:local # rebuilds the webview + extension, packages
# a .vsix, installs it over the previous oneRequires the VS Code code CLI on your $PATH — Command Palette → Shell Command: Install 'code' command in PATH.