Traverse

Survey the workspace you have open as an isometric city.

VS Code shows you a codebase as a list of names in a tree. That tells you where files sit and nothing about what they weigh, what they lean on, what they are built with, or which ones the whole thing rests on.

Traverse draws the same repository as ground you can walk. Every file is a solid with real mass. Hover any of them for what it does and the stack that reaches it — with the evidence that proved it.

The drawings on this page are Traverse surveying its own repository. Nothing is mocked up.

📐 What the drawing means

Colour and hatch carry two different facts and never fight over one. Colour is the language; hatch is the role — what the file is for. Press C to put role on the plane instead, on a dark-to-light value scale.

The Key sits on the drawing itself, bottom right, because a survey without a key is a decoration. It lists only the languages this workspace actually contains, commonest first, with file counts — and every row is a control: click one to show only those files.

Districts follow the real folder tree, so the map matches the mental model you already have.

✦ Features

Clicking traces a file

Selecting a solid draws what that file is connected to, in two directions at once, with the import routes lit as ribbons and the rest faded to a whisper.

• Signal orange — downstream. What imports this file, transitively. The blast radius: what a change here would reach.
• Deep teal — upstream. What this file imports. What it rests on.

The status line reports the count in words: "model.ts — changing it reaches 35 files." Press B for the blast radius alone. Esc clears it.

The core sample

Select any building and the Field Card cuts a core sample: the file pulled and stood on end, imports at the bedrock, exports at the cap, band thickness in proportion to line count, each band hatched with the same mark its role wears on the plane.

The bands carry symbol names, never source text — a deliberate limit.

The survey query

Type / then firebase, and every file that actually touches Firebase lights up — not every file with the word somewhere in its path.

Overlays

Churn, weathering, orphans, cycles and scaffolding wash the ground without repainting it, so the colour underneath stays readable and switching one on does not throw away the reading you had.

Plan view

P looks straight down, like a site plan — the import graph as orthogonal routes between districts.

Poster and Browser

Poster exports the current view as a true vector SVG with the key and metrics baked in — sharp at A1, and openable in a vector editor.

Browser writes the survey as a single self-contained page and opens it — the same drawing and the same controls, for a second monitor or for sending to someone who was not here. It is deliberately a file, not a server.

🖼 Two palettes

Survey Table by day; Drafting Lamp on a dark theme — the same drawing under a lamp, not a second product.

Under a high contrast theme Traverse hands over to your editor's own colours entirely, because someone running high contrast has told the editor that legibility beats decoration — and a drawing board is decoration.

⌨️ Usage

Requires VS Code 1.90 or newer.

Traverse is on the pre-release channel. Everything described here works and is covered by tests, but it has not yet met many repositories other than its author's. If you hit something wrong, an issue is genuinely useful right now.

Install from the Marketplace — search Traverse in the Extensions view (Ctrl+Shift+X), then press Switch to Pre-Release Version. Or run:

ext install abhinavkushagra.traverse

Or install a release build — download the .vsix from Releases and run:

code --install-extension traverse-<version>.vsix

Then run Traverse: Survey This Workspace from the command palette, or press Ctrl+Alt+M (Cmd+Alt+M on macOS). A few hundred files take about a tenth of a second.

Getting around

Every control explains itself: hover or tab to any chip, key row or hint and it says what it does, in a sentence.

Commands

⚙️ Customization

The scan and git settings are machine-scoped on purpose: a repository must not be able to raise a ceiling from its own .vscode/settings.json.

The palette switch in the rail (T) writes the setting rather than holding the choice for the session, so the rail and the Settings UI are one control with two surfaces and cannot drift apart.

🔒 Privacy and security

Traverse reads every file in your workspace, so the security work is not a section at the end — it is the shape of the architecture.

• No network. The webview's content security policy sets connect-src 'none', so telemetry is not disabled by a setting; it is impossible in the page. Dependency enrichment is opt-in, off by default, and asks for per-workspace consent naming the exact hosts and the exact data.
• Secrets are never opened. .env*, key material, .npmrc, credentials files and the like are counted and drawn as sealed vaults. You can see on the map exactly which files were refused.
• No file contents leave the analyser. The webview receives structure and symbol names, never source text — and, by CSP, has nowhere to send them.
• Ceilings on everything: file count, file size, depth and wall-clock, all machine-scoped.
• Untrusted workspaces draw from the file inventory only. Nothing is parsed, git does not run, and enrichment cannot be switched on.

Every one of those claims has a test that fails the build if it stops being true. The reasoning, the known limits and what is deliberately out of scope are in the threat model — or run Traverse: Show What Traverse Reads from the palette.

♿ Accessibility

The whole survey is also emitted as a real DOM tree — headings, lists, focusable rows, one per file — visually hidden until you tab into it. It is the screen-reader view and the keyboard view.

It is also the fallback. If WebGL is unavailable — remote SSH, a VM without a GPU, software rendering — that view takes the whole pane rather than showing you a dead canvas. If VS Code reports a screen reader attached, it becomes the view.

The scene has no motion to reduce; it renders on demand behind a dirty flag. What motion exists in the chrome is turned off by either signal: the operating system's prefers-reduced-motion, or VS Code's own workbench.reduceMotion.

The keyboard focus ring uses --vscode-focusBorder in every palette, not just theme mode.

Contributing

Bug reports and pull requests are welcome — see CONTRIBUTING.md for the architecture, the test suites and how to run the headless survey tool.

Licence

MIT. See LICENSE.