OpenXR Project Atlas

Walk through any codebase inside a Meta Quest headset.

OpenXR Project Atlas turns a local project into a spatial map: folders become districts, files become towers, imports become glowing paths, and TODOs become hotspots. It runs as a WebXR app in Quest Browser and includes a zero-dependency Node scanner plus a tiny local server.

Why this exists

Most code tools flatten projects into lists. Atlas makes structure visible. It is built for demos, onboarding, code reviews, architecture walkthroughs, and anyone who wants to literally step inside a project.

Features

• WebXR scene for Meta Quest Browser
• Desktop fallback with mouse picking
• Project scanner for JS, TS, Python, Swift, C#, JSON, Markdown, and more
• Folder/file topology, import edges, line counts, size, TODO/FIXME hotspots
• Search and focus mode
• No build step required
• Local-only by default: your source map stays on your machine
• Quest helper script using ADB reverse, so http://127.0.0.1 works inside the headset
• Workbench bridge for source previews, notes, VS Code handoff, and rescans
• In-scene XR HUD, so selected files remain readable inside the headset scene
• Walk, Fly, Map, and Focus modes for moving through the project, rising above it, reading relationships from above, and zooming into a selected file

Quick Start

git clone https://github.com/ALHEES/OpenXR-Project-Atlas.git
cd OpenXR-Project-Atlas
npm run demo

Open on desktop:

http://127.0.0.1:5177

Open on Quest:

powershell -ExecutionPolicy Bypass -File tools\quest-open.ps1

In the headset, press Enter VR.

The repository ships with a small demo project, so the first run works before you scan your own code.

Scan Your Own Project

node tools\scan-project.mjs C:\path\to\your-project public\project-map.json
npm run serve

Then open the URL on desktop or Quest.

Before publishing a fork or demo, review public/project-map.json; it contains project metadata such as paths, imports, symbols, hotspots, and line counts. Use the demo map for public repositories:

npm run demo:map

Workbench Actions

When the local server is running, Atlas can do more than display a map:

• View file streams source code into the workbench panel
• Explain generates a no-key local summary by default
• Open in VS Code opens the selected file on the desktop
• Open project opens the scanned project folder
• Refresh map rescans the project and rebuilds the atlas
• Spatial note saves a note for any node and marks it in the 3D scene

The bridge is local only. It reads files from the project root stored in public/project-map.json.

Explain Providers

Atlas ships with two no-setup providers:

• local-summary: default. Uses project metadata, imports, symbols, hotspots, and file role heuristics.
• mock: test provider for verifying the Explain flow without analysis.

Example API call:

Invoke-WebRequest -Uri http://127.0.0.1:5177/api/explain -Method Post -ContentType application/json -Body '{"path":"src/app.js","provider":"local-summary"}'

Quest Controls

Inside VR:

• Use the Walk chip for free movement: left stick moves, right stick snap-turns
• Use Fly to rise above the project: left stick drifts, right stick climbs or descends
• Use Map for a top-down import map pinned in front of you
• Use Focus after selecting a tower to pull that file into a close reading view
• Use Panel to cycle the workbench between docked, centered, and hidden
• Hold trigger or grip on the workbench panel to move and pin it somewhere else
• Aim the controller ray at a file tower or folder disk
• Press trigger to select it
• Press grip while a file is selected to stream source into the workbench
• Aim at the floating action chips for View, Explain, Open VS, or Refresh
• In the code workbench, the right stick can scroll loaded source code
• A/B buttons try to open the selected file in VS Code when the browser exposes them

What gets scanned

Atlas reads project metadata only for visualization:

• relative file paths
• folder structure
• file sizes and line counts
• imports/requires/usings
• TODO/FIXME style hotspots
• a small list of symbols such as functions/classes where easy to detect

It does not upload anything. The generated map is written to public/project-map.json.

Release Scope

This repo is designed to be good enough for a public first release:

• polished WebXR interface
• practical scanner
• Quest launch script
• docs and architecture notes
• MIT license
• demo project included

Open Source Readiness

• MIT licensed
• GitHub Actions check workflow
• issue and pull request templates
• security and contribution guides
• demo map generated from examples/demo-project, not a private workspace

Roadmap

• WebSocket live reload while editing
• AI summaries from local or hosted models
• richer language parsers via Tree-sitter
• spatial anchors in native Quest builds
• multiplayer project walkthroughs
• Git history timeline

License

MIT