Skip to content
| Marketplace
Sign in
Visual Studio Code>Visualization>Aura 3D VisualizerNew to Visual Studio Code? Get it now.
Aura 3D Visualizer

Aura 3D Visualizer

monticma

|
174 installs
| (0) | Free
Visualize your codebase in 3D directly in VSCode — interactive dependency graph with force-directed layout
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

✦ Aura Visualizer

Visualize your codebase in 3D directly inside VS Code
Interactive dependency graph • Force-directed layout • AI-ready

Languages VS Code License

Aura 3D Visualizer — interactive dependency graph


What's New in 1.6.2

  • 🧭 Aura, in the Explorer. A new Aura section sits under the file tree and reads the file you are editing: one card with its metrics, its risk score and the written reasons behind it, the complexity sparkline, its flags (cycle, dead exports, architecture violations, uncommitted, parse error) and the connection map the City inspector draws — dependencies on the right in blue, dependents on the left in amber.
    • It knows where you are. Switching editor tabs rebuilds the card. There is nothing to select, and nothing to point at one by one.
    • Read it, then act. ◫ View in sends the file to the 3D graph, the City or the Treemap — the same menu as the detail panels — 💥 Blast shows what would break, and clicking any name, the file's own or a neighbour's, opens it in the editor.
    • No file open? It falls back to the repository: files and links, the riskiest files with their scores, how many are in cycles, dead, in violation or uncommitted.
    • Free of charge. Everything on the card comes from caches the host already keeps — the graph, the risk snapshot, the .aura/history deltas — so it works with the Aura panel closed and costs one message per editor switch.

Previously in 1.6.1: a query language and one floating palette for every view, right-click a file in any list or on a City building, the tilted centrality orbit and its moon, and menus drawn above the hover tooltips.

Previously in 1.6.0: Code City — the same graph read as a city, in its own tab with its own scene, hot band, relation-coloured selection, district drill-down, function granularity and a postcard export — Risk score v2 (rework volume, recency, authors, fix ratio), one toolbar shell and one control vocabulary in every bar, organised Settings and a searchable two-pane Help, and one Export menu per view next to a single ◫ View in.

Previously in 1.5.2: global-use edges for plain <script> files, a layout that stays put when files come back, silent spread/DAG reflows, case-insensitive layer globs, four new agent tools and the navigation trail.

Previously in 1.5.1: shareable view links, branch review, transitive imports, Find Symbol, architecture rules with baseline and structured editors, the parse-failure report, the Communities/Layers palette with Ask Aura, gamepad pilot mode, Symbol CodeLens, blast radius from the code, import hover and a single status-bar switch.

Features

3D Force-Directed Graph

Files become interactive 3D nodes, dependencies become edges. The graph uses physics simulation to arrange nodes organically — highly connected files cluster together, isolated files drift to the periphery.

  • Node size scales with lines of code (cube root)
  • Edge colors reflect dependency type (import, include, function call, etc.)
  • Directional arrows show dependency direction
  • Animated particles flow along highlighted paths

Code City 🏙️

The 🏙️ City tab is the same graph read as a city — its own tab, its own scene and camera, so orbiting here never touches the 3D graph. Every file is a building and every channel of the city is a control in its bar:

Channel What it encodes
Height cognitive (default), cyclomatic, lines, fan-in, fan-out, PageRank or risk
Footprint the file's size, distributed by √ (default), linear or log
Colour the height ramp, the risk score, the language, the layer or the district
Districts its folder (default), its architecture layer or its community

Mapping is quantiles, linear or thresholds — quantiles keep a small repository's skyline readable.

  • The hot band — 5 % of the buildings, never fewer than 3 nor more than 20 — takes the red end of the ramp and a #1…#N badge. Everything else is muted, so the eye only goes where it matters, and the red always means "the handful you can count".
  • Not everything is ranked — documentation, data, config and assets are drawn as grey glass: visible, but clearly outside the ranking.
  • Click a building: it turns white, the files it depends on turn blue, the files that depend on it turn amber, files in both directions turn purple, and the rest of the city dims — outlines included, one notch darker than the facade.
  • Double-click a building to open the file in the editor — at its line when the city shows functions. District names hang off the edge of the plan on leader lines, and are occluded by the buildings in front of them.
  • Drill down: click a district plate to enter a folder; the breadcrumb and the child chips at the bottom walk back out.
  • Function granularity builds one tower per function and turns the file into the district (~5 000 buildings on a repository this size). The city grows with √building count while the ground keeps a fixed grid, so the streets stay a ruler at every size; above 1 500 buildings contact shadows switch themselves off.
  • Inspector — metrics, district, the risk score with its reasons and the complexity sparkline, a mini map of the file's relations, and the shared action bar: ↗ Open in the editor, ◫ View in another view.
  • Same furniture as the graph — a floating 🗺️ Map with the camera footprint and a reframe button, 🌀 Warps scoped to the City (a pose saved here is not offered in the graph), and 📤 Export → PNG or a 1600×900 postcard with a caption naming the method and the hottest buildings.
  • The legend (bottom left) explains the encoding and carries the switches for district names, rank badges and shadows.

Multi-Language Support

Powered by Tree-sitter AST parsing (WASM) for accurate, structural code analysis.

Language Extensions Color
C source .c 🔷 Light blue
C header .h 📘 Sky blue
C++ .cpp, .cc, .cxx, .hpp, .hxx, .hh 🔹 Steel blue
JavaScript .js, .jsx 🟡 Yellow
TypeScript .ts, .tsx 🔵 Blue
Python .py 🟢 Green
Java .java 🔴 Red
Go .go 🩵 Cyan
Rust .rs 🟠 Orange
Kotlin .kt, .kts 🟣 Purple
Ruby .rb ❤️ Red
Swift .swift 🟥 Coral
C# .cs 💜 Violet
PHP .php 🐘 Periwinkle
Vue .vue 💚 Vue green
Bash .sh, .bash 🐚 Lime
Lua .lua 🌙 Indigo
CSS .css 🟣 Purple
HTML .html 🟧 Coral
Documentation .md, .markdown, .txt, .rst 📄 Slate

Cross-file function calls are detected for C, C++, JS/TS, Python, Java, Go, Rust, Kotlin, Ruby, Swift, C#, PHP, and Lua. Inheritance edges (extends / implements) are detected for JS/TS, Python, Java, Go (struct embedding), Rust (trait impl), Kotlin, Swift (protocol conformance), C#, and PHP. Language filter buttons are dynamic — only languages present in the current analysis are shown.

Import Resolution & Aliases

Imports are resolved through the project's real configuration, not just relative paths:

  • tsconfig.json / jsconfig.json — compilerOptions.baseUrl and paths (including @/*, ~/lib/*, @app/* and simple relative extends chains)
  • Vite / webpack — static resolve.alias entries such as '@': path.resolve(__dirname, './src')
  • Python src/ layout — app.models.user → src/app/models/user.py (or __init__.py)
  • Historical fallbacks stay available: relative imports, extension/index probing, vendored suffix matches and basename matching.

This removes the false “orphan” nodes that aliased imports used to create. The same resolver is used by the history worker, so temporal deltas stay consistent with the current graph.

Edge Confidence

Every edge carries a confidence score: 1.0 exact/relative/alias, 0.9 extension or index, 0.8 vendored suffix, 0.6 basename, 0.5 ambiguous (multiple candidates). Function-call edges are 0.8 when the target is unique and 0.5 when several definitions match; heritage edges are 0.9. Use the Edge confidence selector in the toolbar to hide low-confidence links, inspect the per-edge badge in the detail panel, or read the edges array (with confidence) from the aura://node MCP resource. Legacy databases default to 1.0.

PageRank Centrality 💠

Aura computes a PageRank centrality over the structural code graph (source → target = "depends on"; damping 0.85, 40 iterations, normalized scores): a file is central when the files that depend on it are themselves central, not just numerous. Documentation and doc-reference links are excluded from this graph and from fan-in.

  • Detail panel — the Centrality metric shows the PageRank score (0.0042, hover for context)
  • 💠 Centrality toolbar button — marks the top 10% most central code files with a soft violet halo, a tilted dashed orbit and a moon circling it; off by default and persisted in the view state
  • Risk score — optional auraVisualizer.riskCentrality setting replaces the fan-in percentile with the PageRank centrality percentile (same 0.20 weight); disabled by default so existing scores are unchanged
  • MCP / resolve_context — ranking uses PageRank when available, falling back to fan-in for older databases
  • The halo is deliberately subtle, but the orbit is not: a glow alone sat in the camera plane, at the same radius as the amber dirty ring and the note ring (all three peak at ≈2.4× the node radius), so they washed each other out. The dashed orbit is drawn at ≈3.4× the radius and tilted out of that plane, and the moon adds a motion cue nothing else in the graph uses. Moons are phase-shifted per file, dropped above 240 haloed files (the ring stays), and frozen under prefers-reduced-motion

Interactive Exploration

Action Effect
Click Select node, show detail panel, focus camera (auraVisualizer.focusDistance, default 120 units)
Double-click Open file in VS Code editor
Right-click Pin focus — isolate file + neighbors up to N depth
Click an edge Frame both endpoints and glow the edge pink — the glow follows the link itself (the Bézier tube in curved mode), the camera keeps its angle and pulls back just enough to fit the pair; the edge stays lit until the next click. Both files are multi-selected too, so the detail panel shows their aggregate stats (auraVisualizer.edgeClickSelect turns the selection off)
Shift+Right-click Blast radius — show impact (all dependents) with depth coloring
Shift+Click Multi-select — aggregate stats for multiple files
Scroll Zoom in / out
Drag Rotate the 3D view
Background click Clear all selections

Detail Panel 🗂️

Click a file node to open a collapsible detail panel:

  • 📋 File details groups the file metrics (including Layer), Ask Aura actions and the 📝 Note editor in one foldable section
  • 🏛️ Architecture lists the file's layer and every outgoing rule violation with its severity, target and link types (baselined ones stay visible)
  • Symbols, Dependencies and Dependents are collapsible too, and render as readable cards (name/signature/metrics on separate lines, path + type + confidence for edges)
  • 🔗 Transitive imports / 📥 Transitive dependents — expand one to get the full closure computed on demand: Imports 42 files · depth 4, the deepest chain (extension.ts → codelens.ts → graph-db.ts) and one row per file with its depth badge (direct files in bold, click to select). Cycle-safe, deterministic, capped at 500 files; auraVisualizer.transitiveDepth (1–10, default 5) sets how many hops are followed. The same closure enriches the find_dependencies / find_dependents MCP tools with max_depth, by_depth, longest_chain and truncated
  • Empty sections are hidden automatically — no empty Dependents block, no Symbols block for a file without symbols
  • Section open/closed state is kept while the webview stays open

Heatmap Modes

Color every node by a metric to spot hotspots at a glance. Press H to cycle through:

Mode Description
Off Color by programming language
Complexity Cyclomatic complexity (branching, loops)
Cognitive Highest per-function cognitive complexity in the file — supported for JS/TS/TSX, Python, C/C++, Java, Go, Rust, Kotlin, Swift, C#, PHP, Lua and Bash
Fan-in How many files depend on this file
Fan-out How many files this file depends on
Lines of Code File size
Churn (commits) Git commit count per file — requires Time Travel scan
Co-change Strongest temporal-coupling Jaccard score per file — requires Time Travel scan
Last Modified File modification time (most recently changed = red)
Architecture layers Layer colors from .aura/arch-rules.json; forbidden edges turn red, baselined ones amber. The floating palette switches between Communities and Layers and hides the layers you switch off
Communities Architectural modules detected by Louvain algorithm

Blue = low, Red = high. A legend displays the value range.

Community Detection

The Communities heatmap mode uses a single shared code-only Louvain snapshot computed by the extension and reused by the webview, @aura and MCP. Documentation nodes and doc-reference edges remain visible in the graph for exploration, but they are excluded from communities, fan-in, PageRank and risk: documentation is not architecture.

Each community gets a unique color and an automatic label equal to the full path of its hub file (highest structural fan-in, deterministic tie-break). The palette uses readable cards showing:

  • color swatch, label and hub path
  • code file count, plus the currently visible count when filters hide members (31 files · 18 visible)
  • ✏️ Rename — a custom label persisted by member-set hash; empty restores the hub path
  • ✨ Ask Aura — sends the exact member files as the authoritative scope
  • All / None buttons for batch selection

Unselected communities are grayed out (nodes + links), just like pin focus. Others collects isolated code files. Documentation nodes stay in the graph with yellow labels, so docs remain distinguishable from code even when a heatmap is active.

Blast Radius

Shift+Right-click on any file to see its impact radius — all files that transitively depend on it. Nodes are colored by depth of impact:

Depth Color
Source White (orange glow halo)
1 Red
2 Orange
3 Yellow
4 Yellow-green
5 Green

Use the Depth slider (1–5) or keys 1–5 to control the blast radius depth.

From the code side — the same analysis is one click away where you work:

  • Source Control: right-click one or several changed files → Aura: Blast Radius. A multi-selection seeds the impact cascade (every selected file at depth 0, dependents colored by depth)
  • Editor title: the radio-tower icon on the file's tab, the same entry in the editor right-click menu, and in the Explorer file context menu
  • Files outside the workspace or not part of the analyzed graph are skipped; the panel is only opened when at least one file matches

File Explosion

Expand any file into its internal symbols — functions, structs, enums, macros. Each symbol becomes its own node, connected to the parent file. Double-click a symbol to jump to that exact line in the editor.

Path Finder

Find the shortest dependency path between any two files. Click Path in the toolbar then select source and destination. The path lights up with animated particles.

Dead Code Detection ☠️

Press X or click the Dead Code button. Files with unused exports are highlighted in orange-to-red gradient. The detail panel lists each unused export with a ⚠️ label.

Framework/test exemptions (V2-13) keep framework-owned entry points and callbacks out of the dead list: main, VS Code activate/deactivate, React components in .tsx/.jsx, Vue lifecycle hooks, SwiftUI body, Java servlet methods, Unity callbacks, Arduino setup/loop, and test files. Exempted symbols remain visible in the detail panel with their reason instead of being silently hidden.

Open ⚙️ Settings → Dead code exemptions → Edit rules… to edit .aura/dead-code.json with a structured editor: each rule is a form with a required reason, exact symbol names, an optional regex, path globs, languages and kinds. Rules can be reordered (first match wins), removed, and are validated by the same parser as the analysis before Save is enabled. The built-in defaults are listed read-only; raw JSON remains available for advanced cases.

The defaults stay active; custom rules are merged after them. Equivalent file example:

{
  "rules": [
    { "name": ["onResume", "onPause"], "language": ["kotlin", "java"], "reason": "Android lifecycle" },
    { "path": ["src/gen/**"], "reason": "Generated code" }
  ]
}

A rule needs a reason and at least one of name, namePattern or path; language and kind are optional filters. Saving starts a re-analysis so the dead-code list updates immediately.

Risk Map 🛡️

Open the 🛡️ Risk tab for a codebase health dashboard built on a transparent, explainable risk score:

risk = 100 × (0.21·complexity + 0.18·centrality + 0.08·fan-out + 0.12·cycle + 0.12·dead-code + 0.09·rewrite + 0.06·recency + 0.06·frequency + 0.05·authors + 0.03·fixes)

The structural half stays dominant on purpose — Aura is an architecture tool, and git history refines the ranking rather than driving it. Rewrite is the volume of lines added and removed inside the window relative to the file's size today, recency weights a commit made today over one at the window's edge, frequency is the commit count, authors the number of distinct authors and fixes the share of commits whose message looks like a bug fix.

centrality is fan-in, or PageRank when auraVisualizer.riskCentrality is on.

Documentation files are outside the architectural risk model: they are not scored, and doc-reference links do not inflate fan-in or PageRank. The doc links remain visible in the graph for exploration.

Complexity, fan-in, fan-out and churn are percentile ranks inside your repository (0 = lowest file, 1 = highest), so a score is a standing relative to your codebase rather than an absolute threshold — a 72 means the same thing in a 50-file project and in a 5 000-file one. Cycle and dead-code are ratios by nature.

  • Codebase Health — overall health score (100 − average risk), plus the most risky and most connected files
  • Risk Distribution — high / medium / low buckets with percentages
  • High / Medium / Low files — collapsible lists (▼/▶ arrows); each file states why it scores that way ("changed 29 times in 90 days (top 1%)", "12 files depend on it"), with the full breakdown on hover. Click a file to select it and focus it in the 3D graph.
  • History window — pick 30 / 90 / 365 days of git history; it drives churn, scoring and the explanations. Also available as the auraVisualizer.riskWindow workspace setting, shared with the status bar and the MCP get_hotspots tool
  • Rename-aware churn — files moved with git mv keep their history: churn, bus factor and the written explanations follow the rename (chained renames collapsed, latest one wins)
  • 🛡️ Status bar — the risk of the file you are editing (Risk 72 · top 8%, written reasons in the tooltip); it switches to ⚠ N hotspots in your changes when your working tree touches high-risk files. Click to jump to the file in the Risk tab. Deleted files never count (a removed hotspot is no longer at risk), and a single switch — auraVisualizer.statusBar — hides every Aura badge
  • 📈 Risk Trend — average complexity over git history (structural risk proxy)
  • 🔥 Recently Hot — files modified most in the last 30 days
  • 📊 Churn × Complexity — scatter matrix (log scale) spotting files that are both complex and heavily churned (red = hot)
  • 👤 Bus Factor — files touched by a single developer (≥ 3 commits in the window)
  • 📤 Export — writes a Markdown report to .aura/risk-report.md, reasons included
  • 📷 PNG — exports the 3D graph at ×1/×2/×4 with current or transparent background, optional watermark, and a unified save dialog. The button only shows on the 3D Graph tab, because that is the only tab with a live WebGL canvas

Risk buckets: High ≥ 66, Medium 33–65, Low < 33. Churn is measured as commits per file and requires the git Time Travel scan.

Complexity Trends 📈

The Risk dashboard and the Table tab add a per-file complexity trend derived from the commit deltas already collected by Time Travel:

  • Sparkline — complexity across the file's changed commits, colored red when degrading and green when improving
  • Slope + R² — linear regression of complexity over time; the badge shows the slope per 30 days
  • Degrading badge — shown when the slope crosses auraVisualizer.complexityTrendThreshold (default 0.5) and the fit is meaningful (R² ≥ 0.3)
  • Risk dashboard — a collapsible 📈 COMPLEXITY TREND section ranks the top files by slope; click a row to focus it in the graph
  • Rename-aware — historical paths follow git renames and are merged under the current file id, so trend rows focus the right node
  • Table — sortable Trend column with the same sparkline/badge
  • Short histories are safe: one sample gives —, never NaN; removed files are dropped and a re-add starts a fresh series

Temporal Co-change 🔗

Open the 🔗 Co-change tab after a Time Travel scan to find files that keep changing in the same commits without a direct dependency — implicit contracts (API + client, test + implementation, shared configuration…).

  • Jaccard score — cochanges / (A commits + B commits − cochanges), plus support (share of analysed multi-file commits touching both)
  • Window & threshold — 90 days / 365 days / 2 years, minimum score 0.2–0.6
  • Rename-aware — git mv history follows the current path; deletions and giant commits (>50 files) are ignored
  • Show on graph — adds virtual magenta co-change links for the strongest pairs; the 🔗 Co-change filter toggles them
  • Heatmap + query — color files by their strongest coupling score or run cochange > 0.6
  • MCP / AI — the get_cochange tool exposes the same persisted pairs

Git Working Tree ✏️

Aura reads git status and shows what you are working on right now:

  • Dirty rings — files with uncommitted changes wear a thin amber ring in the 3D graph; the detail panel adds a Git line with the exact state (modified / staged / untracked / renamed / conflicted)
  • ✏️ Dirty filter — toolbar button showing only files with uncommitted changes (nodes and links)
  • Query flag — dirty works in the query palette: dirty AND complexity > 20
  • Status bar alert — when your changes touch high-risk files, the status bar switches to ⚠ N hotspots in your changes (see Risk Map)

Everything refreshes automatically on save (debounced, no shell involved).

File Notes 📝

Annotate any file with a personal, color-coded note — a marker that follows you through the graph:

  • Write a note — click a file node: the detail panel shows a 📝 Note section with a text area (up to 2 000 characters) and five colors (yellow, red, blue, green, purple). Save applies it, Delete removes it
  • Pulsing indicator — annotated files wear a note-colored ring + dot in the graph, animated (breathing) so they stand out at any zoom level; the ring nests inside the amber dirty ring when a file is both annotated and modified
  • 📝 Notes toggle — toolbar button next to ✏️ Dirty: shows / hides all note indicators; the choice is saved with your view state
  • Stale notes — when a file changes after its note was written, the note header shows ⚠️ À revoir, ✓ Mark reviewed refreshes its timestamp, the 📝 Notes button shows the exact count and the ⚠️ Stale filter isolates those files
  • Query flag — hasnote works in the query palette: hasnote AND complexity > 20; use stalenote for notes older than their file
  • Storage — notes are stored in .aura/annotations.json, local to the workspace (not committed)

Circular Dependencies 🔄

Press C or click the Cycles button. All nodes involved in circular dependency chains are highlighted in orange. The detail panel shows the full cycle paths.

Architecture Rules 🏛️

Architecture rules are a fitness function: they turn the dependency graph into an executable constraint checked on every analysis. Declare them in .aura/arch-rules.json:

{
  "version": 1,
  "edgeTypes": ["import", "import-type", "require", "dynamic-import", "extends", "implements", "function-call"],
  "layers": [
    { "name": "ui",             "paths": ["src/ui/**", "src/components/**"] },
    { "name": "application",    "paths": ["src/app/**", "src/services/**"] },
    { "name": "domain",         "paths": ["src/domain/**", "src/models/**"] },
    { "name": "infrastructure", "paths": ["src/infra/**", "src/db/**"] }
  ],
  "rules": [
    { "id": "domain-pure", "from": "domain", "deny": ["ui", "application", "infrastructure"], "severity": "error" },
    { "id": "app-no-ui",   "from": "application", "deny": ["ui"] },
    { "id": "slices", "type": "slices", "pattern": "src/features/*", "shared": ["src/shared/**"], "severity": "warn" },
    { "id": "no-layer-cycles", "type": "no-cycles" }
  ],
  "exceptions": ["src/domain/legacy/**"]
}
  • layers — first matching glob wins (*, **, ?); matching is case-insensitive (src/Agent/** also captures Src/Agent/…) and the layers editor shows how many files each row captures; files matched by no layer are reported as unlayered (never silently ignored)
  • from + deny — every real edge in that direction is a violation; "*" means any other layer
  • slices — sibling folders captured by the pattern may not import each other; shared globs are allowed
  • no-cycles — Tarjan SCCs on the aggregated file → layer graph
  • exceptions — source globs exempted from every rule
  • severity — error (red) or warn (amber), default warn
  • Baseline — .aura/arch-baseline.json freezes legacy violations; only new ones alert. Write it from the Architecture tab or the command palette
  • Martin metrics — per layer Ca (external files depending on it), Ce (external files it depends on) and instability I = Ce / (Ca + Ce)
  • Documentation is outside the model — .md nodes and doc-reference edges are never evaluated, even if listed in edgeTypes

Surfaces:

Surface What it shows
🏛️ Architecture tab Rule-by-rule violations, layer table with Ca/Ce/I, aggregated cycles, unlayered files, baseline and Markdown export
Architecture layers heatmap Nodes colored by layer; forbidden edges in red, baselined edges amber; the floating palette switches between Communities and Layers and hides the layers you switch off (selections persisted)
Status bar Current file's layer, or 🏛️ N arch violations; tooltip lists every offending import
Detail panel Layer + every outgoing violation with its rule, target, link types and baseline state
Matrix / Chord Group by → Architecture layer; violating DSM cells turn red with ✖
Table Sortable Layer column
Query DSL layer == domain AND archviolations > 0, isarchviolator
Ask Aura / AI ✨ on a layer card sends its globs, members, coupling, violations and cycles to @aura; the aura_get_architecture_violations LM tool (and MCP) returns the same evaluation with an optional layer filter
MCP get_architecture_violations returns new violations, layer metrics and cycles

Create the rules file from your top-level src/ folders with Aura: Create or Open Architecture Rules. The ⚙️ Edit rules button in the Architecture tab (also in ⚙️ Settings → Architecture rules) opens a structured editor: add/reorder layers, toggle forbidden targets per deny rule, edit slices/shared globs, add no-cycles, exceptions and strict mode. Layer renames update every rule reference, and the exact analysis engine validates the form before saving (the raw JSON field stays available for edgeTypes). + Add layer seeds a ready-to-save layer-1 → src/layer-1/** and selects its name, deleting a layer drops the deny rules that started from it, every row shows how many files its globs capture (with a ⚠ 0 file warning that updates while you type), and a disabled Save carries the validation message as its tooltip. Saving re-evaluates immediately — no re-parse.

The floating Communities / Layers palette shows one card per layer with its globs, member count and new violations. Click a card to hide that layer, or ✨ to ask @aura for an explanation: the request carries the authoritative member list, the rule globs, Ca/Ce/I, new vs baselined violations and aggregated cycles, so answers separate code fixes from rule changes. The Unlayered bucket can be toggled but has no ask action yet.

Parse Failures ⚠️

A file that Tree-sitter cannot parse cleanly (syntax errors) or that makes a parser throw is never dropped from the graph: its node stays, so imports and dependents remain visible, and the failure is recorded with a short reason.

  • The stats bar shows ⚠ N parse failures when the analysis reported at least one.
  • Clicking the badge opens a panel with the sampled paths and reasons; clicking a path reveals the node in the 3D view.
  • The report holds the exact failure count plus a deterministic sample (25 entries), is persisted in .aura/graph.db, and follows incremental edits (a fixed file leaves the list, a newly broken one joins it).
  • Export report writes a Markdown summary (parse-failures.md). No analysis aborts on a broken file.

Orphan Detection

Press O to highlight isolated files (zero incoming and outgoing dependencies) in red. Useful for finding dead files that nothing references.

DAG Mode

Press D to switch from physics-based layout to a hierarchical top-down Directed Acyclic Graph layout. Entry-point files float to the top, leaf dependencies sink to the bottom.

Directory Clustering

Press G to group files by directory. Directories become translucent spheres containing their files. Click a cluster to expand or collapse it.

Multi-Selection

Hold Shift and click multiple nodes to select a group. The detail panel shows:

  • Combined LOC and average complexity
  • Language breakdown
  • Internal links between selected files
  • List of all selected files

Minimap 🗺️

Toggle with the 🗺️ Map button in the toolbar. A floating minimap displays a real-time overview of all nodes, projected from the camera's perspective. The white rectangle shows the current viewport.

  • Rotate the 3D view — the minimap rotates in sync
  • Drag inside the minimap — pan the camera in the 3D view
  • Drag the header — reposition the minimap panel
  • Close with the ✕ button or toggle the toolbar button

Aura in the Explorer 🧭

The Explorer carries an Aura section right under the file tree. It is a read-out of the file you are editing — the 3D detail panel's metrics and the City inspector's risk block, in one card you never have to open a tab for:

Block What it says
Identity file name, folder, LOC · complexity · cognitive · fan-in / fan-out — click the name to open the file
Flags ✏ modified ⚠ parse error ⟳ N cycles ☠ N dead exports 🏛 N violations — only when something is true
Risk the score the Risk tab ranks by, its bucket, the written reasons, the commits · rewritten · fixes · authors line and the complexity sparkline with its ▲ +N/30d badge — the same ramp, geometry and tooltip as the Risk tab and the City inspector
Connections the City inspector's relation map: dependencies on the right in blue, dependents on the left in amber, documentation references counted apart. Every dot carries its path and its edge type in the tooltip, and opens the file on click. Two neighbours that share a file name are prefixed with the folder that tells them apart (out/city.js vs webview/city.js)
Actions ◫ View in — 3D Graph, City or Treemap: the panel opens on that file, on that tab — and 💥 Blast (everything impacted if it changes)
  • It follows the editor — switch tabs and the card changes. No selection to make, nothing to hover one by one.
  • With no analyzed file open it becomes a repository summary: files and links, the riskiest files with their scores, and how many files are in cycles, dead, in violation or uncommitted.
  • Nothing is recomputed for it: the graph, the risk snapshot and the .aura/history deltas are already in memory, so the card works with the Aura panel closed.

The 🗺️ Map button inside the panel is a different tool: it follows the camera of the 3D graph or of the City. The Connections map is about one file's neighbourhood, not about the whole repository.

Warp Points 🌀

Save named camera bookmarks of the 3D view and fly back to them in one click:

  • 🌀 Warps (top bar, next to 🗺️ Map) opens the panel
  • 📌 capture (in the panel header) — stores the current pose: camera position, orientation and view target — the exact view comes back to the pixel
  • Layout-proof — warps are anchored to the files in view (plus the layout scale), so they land on the same spot even though the force layout differs between sessions
  • Click a warp — smooth ~800 ms flight; ✏️ rename · 📌 re-capture · 🗑️ delete per row
  • Quick slots — assign Alt+Shift+1–9 in the panel; the shortcut flies there from anywhere in the graph
  • 🏠 Home — the first row always returns to the default fit-to-view
  • Stored in .aura/warps.json, local to the workspace (not committed)

Share a View 🔗

🔗 Link (top bar, next to 🌀 Warps) copies a vscode://monticma-aura.aura-visualizer-3D/open?state=… link that reopens the exact same view on another machine or window of the same repository:

  • Carries the tab, every filter (languages, palettes, toggles, heatmap, edge confidence, co-change, sizes), the camera pose — anchored to the files in view, like a warp — and the query expression with its mode
  • Paste it in a chat, an issue, a PR or a README; opening it launches VS Code, opens the Aura panel and applies the view once the graph is rendered
  • Everything is validated on arrival: versioned payload, 8 KB cap, whitelisted keys, clamped numbers, finite camera coordinates — a corrupted or hand-edited link is refused with a message instead of breaking the panel
  • A link captured in another workspace still applies, with a warning naming the folder it came from
  • Aura: Copy View Link in the Command Palette does the same from the keyboard

Navigation Trail 🧭

Off by default — turn it on with auraVisualizer.breadcrumbs (or the Navigation trail checkbox in ⚙️ Settings). Once enabled, every jump — a file click, a search hit, a CodeLens focus, a pin, a blast radius, an applied query, a warp, a shared link — is recorded on a trail shown as a thin strip over the graph:

⟵  ⟡ extension.ts  ›  📌 Pinned: codelens.ts  ›  🔍 layer=web  ›  🌀 Architecture
  • Click a chip to return to that place (selection, pin/blast mode, query, tab and camera pose) and drop everything after it; ⟵ or Backspace / Alt+← steps back one place
  • Consecutive duplicates are collapsed and the trail keeps the last 20 places — visiting the same file twice in a row never fills it
  • Entries store ids and numbers only (never live node or Three.js objects), so a re-analysis can never leave a dead reference behind
  • The strip stays hidden until there is a second place to go back to; ✕ clears it
  • Complements 🌀 Warps (named, persisted poses) and 🔗 View links (shared views): the trail is the session's own history

Follow Editor 👁

Switch editor tabs and the 3D camera flies to the matching file — the same 800 ms close-up and selection as clicking its node:

  • The 👁 toolbar button toggles following; the choice is saved in the view state and as auraVisualizer.followEditor
  • The file is selected like a click: glow, explorer selection and detail panel, with a fixed camera distance (no creeping zoom when alternating files)
  • Any manual orbit, pan or zoom pauses following so the camera never fights you — click 👁 again to resume
  • Files outside the analyzed graph are ignored

Pilot Mode 🚀

Switch from orbiting the graph to flying through it — first-person navigation:

  • Toggle with the 🚀 Pilot toolbar button or Space; Esc (or Space) exits — the orbit controls take over seamlessly at the exact same view
  • W A S D move camera-relative (physical key layout — AZERTY gets ZQSD), Q/E descend / ascend
  • Mouse look with pointer lock; hold the left mouse button to fly forward, the right to fly backward — steer by looking while you hold
  • Wheel adjusts base speed, Shift boosts — the base speed scales with the graph size
  • 🎮 Gamepad (DualSense, Xbox — any W3C standard pad): left stick translates, right stick looks, L2 descends, R2 boosts analogically, ✕ resets the camera to an overview, touchpad re-aims at the graph centre, d-pad ↑/↓ change the speed, Options resets it, ○ exits. Sticks pass a 15% deadzone then a response curve, so fine nudges stay precise; the stick look rate follows the Mouse look sensitivity setting. Pads are only polled while flying (browsers expose a pad after its first button press), and the live pad name shows in the pilot HUD
  • No roll (pitch clamped), smooth acceleration/damping, and single-letter shortcuts, hover and clicks are suspended while flying
  • Flight speed, smoothing, mouse sensitivity, Y-inversion and the gamepad toggle live in ⚙️ Settings

Symbol CodeLens ⟡

Stay in the editor — Aura puts itself above your code:

  • Every symbol of an analyzed file gets a ⟡ focus · flow · impact lens (functions, methods, classes, interfaces, structs, enums, type aliases…). Files Aura never analyzed show no lens at all
  • Click it for a quick pick: ⟡ Focus in Aura (centers the 3D graph on the file), ⑂ Show flowchart (this function's control flow, same renderer as the graph panel) and 💥 Blast radius (every impacted file, colored by depth)
  • Symbols and line numbers come from the graph database, so the lenses are instant and work even when no language server is running; a file analyzed without symbol rows falls back to the editor's document symbols
  • The three actions are ordinary commands — Aura: Focus Symbol in Graph, Aura: Show Symbol Flowchart, Aura: Symbol Blast Radius — so they can be bound to keys
  • Turn it off with auraVisualizer.codeLens (or the CodeLens checkbox in ⚙️ Settings); at most 300 lenses per file

Function Flowcharts ⑂

Turn any function into a readable control-flow chart — without tracing ifs and loops by eye:

  • Click the ⑂ button next to a function in the Explorer symbols list (JS/TS/TSX, Python, C and C++)
  • The chart is built on demand from the AST: conditions fork into T / F branches that re-join, loops get a framed body with their back edge, switch cases line up as columns, and try / catch / finally stack as labelled frames
  • Dead code after a return / throw is drawn as red dashed boxes; the header badge shows the function's cognitive complexity, maintainability index and decision count
  • Function metrics — for JS/TS/TSX, Python, C/C++, Java, Go, Rust, Kotlin, Swift, C#, PHP, Lua and Bash, each function also reports Sonar-style cognitive complexity (nesting + boolean sequences), McCabe cyclomatic complexity, approximate Halstead volume and a 0–100 Maintainability Index. The detail panel shows a cog N · MI N chip (hover for the full breakdown), and the 📋 Table has a sortable Cog. max column
  • Click any step to open the file at that exact line, and click an underlined call chip (↳ validate()) to drill into the called function — the breadcrumb walks back
  • ⤓ SVG exports the chart as a standalone vector file
  • The window is draggable and resizable; Esc closes it

Symbol Cycles 🔁

Aura also detects function→function recursion, not just file-level import loops:

  • Direct recursion — walk() → walk() — is reported as a self-loop
  • Mutual recursion — parse() → validate() → parse() — is reported with the full function chain
  • Every step keeps the call line (file.ts:42), and cycles through same-name candidates are marked ambiguous with a 0.5 confidence
  • The 🔄 Symbol cycles section in the detail panel lists cycles involving the selected file; the function flowchart badge adds 🔁 recursive / 🔁 mutual recursion
  • The Risk dashboard adds a collapsible 🔁 Symbol cycles list with the chain, kind, confidence and ambiguous marker
  • Cycles are persisted in .aura/graph.db (symbol_cycles / symbol_cycle_steps) and recomputed after incremental edits
  • The MCP / @aura find_cycles tool returns both file cycles and symbol_cycles

Dynamic dispatch, callbacks and unresolved calls are not guessed; cycles are built only from statically resolved call sites.

Time Travel ⏳

Navigate your project's git history commit by commit. A timeline bar at the bottom lets you scrub through commits. Changed files are color-coded: 🟢 green = added, 🔴 pink = removed, 🟡 yellow = modified. Edges follow the same color scheme.

Control Action
Timeline slider Jump to any commit
← / → arrows Step through commits
Prev / Next buttons Navigate history
I Toggle impact cascade from changed files
Escape Return to HEAD

Shallow clones — a git clone --depth 1 checkout (actions/checkout does this by default in CI) only exposes one commit, so churn, co-change and complexity trends would be silently underestimated. Aura detects it (git rev-parse --is-shallow-repository, with a .git/shallow fallback for older git) and shows a banner at the top of the Time Travel tab — plus a caption under Codebase Health in the Risk tab — with the fix: git fetch --unshallow (one click to copy). Nothing runs behind your back.

Visual Diff Between Commits 🔀

Press V or click the ⇄ Compare button to enter Compare mode. A second slider appears — drag both sliders to diff any two commits. Files that changed between those commits are highlighted; unchanged nodes are dimmed. Compare mode shows the cumulative diff across the selected range.

Reviewing your branch: run Aura: Review Current Branch (Command Palette, or the compare icon in the Source Control title bar). Aura asks git for git diff main...HEAD — merge-base, --find-renames, --numstat — and shows a strip over the graph: main...HEAD · 12 files · +340 −120 · Δcomplex +18, with 💥 Blast (multi-source impact from every touched file) and ⇄ Compare, which pre-fills the dual slider with the merge-base and HEAD so the visual diff is the existing Compare mode. Renamed files are one entry instead of a delete + an add, and the Δcomplexity only appears when the Time Travel scan covers the branch. Set auraVisualizer.reviewBase to compare against another branch (default: main, then master).

Search

Type in the search box (2+ characters) to find files by name or path — and, since V3-09, symbols too: matching functions/structs appear after the file rows (⚡ icon, path:line) and clicking one explodes the file in the graph and marks that exact function with a one-shot ripple. Results appear in a live dropdown — click to navigate.

From anywhere in VS Code, Aura: Find Symbol… opens a QuickPick over the whole symbol index: kind chips (function (82), method (140), …) as the first rows of the list, live filtering as you type, ↑↓ to navigate, Enter to jump (graph opens on the file, exploded, symbol highlighted and rippled). 10 000 symbols stay instant: the query is capped at 200 rows and the kind chips come from a single GROUP BY.

Import Hover 💬

Hover an import and Aura answers in place — no need to open the graph:

  • Works on import specifiers of JS/TS/Vue (from '…', require('…'), import('…')), Python (import x, from x import), C/C++ (#include), Java/Kotlin (import a.b.C), Go, Rust (use, mod), C# (using), Ruby/PHP (require), Lua and Bash (source)
  • The card shows the target's language, LOC, cyclomatic and cognitive complexity, fan-out/fan-in, architecture layer with its violation count and the risk bucket
  • Three actions: ⟡ Focus in Aura, 💥 Blast radius, 📂 Open file
  • Specifiers resolve with the same confidence ladder as the graph edges; an ambiguous or unknown import shows nothing, and arbitrary text never triggers a hover
  • Metrics come from the in-memory graph and risk snapshot (no SQLite query), lines are cached per document version — turn it off with auraVisualizer.hover or the ⚙️ Settings checkbox

Agent Context Files 🤖

An AI assistant that lands in an unfamiliar repository has no idea which files are dangerous. Aura: Generate Agent Context writes exactly that, from the same risk engine as the Risk Map:

Output Content
.aura/hotspots.json the aura_get_hotspots payload (score, bucket, reasons, fan-in/out)
.aura/HOTSPOTS.md the same data as a readable table — .aura/ is git-ignored, this is a local cache
AGENTS.md / .github/copilot-instructions.md / CLAUDE.md a short aura:begin … aura:end block with the top 10 hotspots, scores and reasons
  • The block is injected between the two markers: regenerating never duplicates it and never touches the prose around it
  • Only paths and metrics are written — never source code
  • The first instruction file that already exists wins (in that order); if none exists the command offers to create AGENTS.md, and it always asks before touching a tracked file
  • auraVisualizer.agentContext (off by default) refreshes everything silently after each analysis — that automatic path only updates a file that already exists

Command Palette 🎛️

Three navigation gestures are one keystroke away from anywhere in VS Code (Ctrl+Shift+P):

Command What it does
Aura: Focus File in Graph… Fuzzy picker over the analyzed files (path, language, directory, LOC, fan-in/out, layer, violations) — selection focuses the node and opens its detail panel
Aura: Apply Saved Query… Replay a query saved from the query palette, most recent first — it applies in the mode currently selected, never forcing the one it was saved in
Aura: Add Warp Here Opens the warp naming modal on the current camera pose (same flow as 📌 in the Warps panel)
Aura: Generate Agent Context Writes .aura/HOTSPOTS.md, .aura/hotspots.json and the aura:begin block of your agent instruction file (V3-10)

Files are code only (documentation nodes are excluded) and the picker caps at 5 000 entries — typing a path fragment narrows it down.

Query Filter 🔍

Filter, highlight, or select files with the built-in Aura Query Language — a small boolean DSL evaluated over node metrics.

  • Open it with the 🔍 button (graph bar) or Ctrl+K / Cmd+K: a floating palette, not a bar — it never takes height away from the graph. It opens centred the first time, then reopens exactly where you dropped it (⟲ recentres, ✕ closes).
  • Type an expression such as complexity > 20 AND fanIn > 5 — results apply as you type, in all three modes (Highlight / Filter / Select): there is no Apply button. The summary line reads N / M files · P%.
  • While a query is applied, a chip in the graph bar recalls it — 🔍 expression · N files · mode: click it to reopen the palette, ✕ on the chip to clear.
  • Two fields, not one: the name comes first (it gets the caret when the palette opens — typing a name never summons the field list) and the expression below. Leave the name empty and one is generated (Query 3) instead of copying the expression.
  • Autocomplete stays out of the way: it appears while you type, or when you ask for it with the ▾ button on the right of the expression (or Ctrl+Space) — that one lists all 30 fields even on an empty field, so you never have to remember a name.
  • ⭐ Save stores the name + expression; saving under a name that already exists updates that query rather than adding a twin. 📚 Saved unfolds the list inside the palette — click a row to apply it, ✏️ renames it in place (Enter saves, Esc cancels), ✕ deletes it.

Available fields:

Field Description
complexity Cyclomatic complexity
cognitive Highest per-function cognitive complexity in the file
loc / linesofcode Lines of code
fanin / fanout Incoming / outgoing dependency counts
size File size in bytes
mtime / lastmodified Last modification time
symbols / symbolscount Number of extracted symbols
deadexports Number of unused (dead) exports
cochange Strongest temporal-coupling Jaccard score (0–1)
churn Commit count touching the file in the Risk window (Settings → Risk & analysis)
language, name, path, group, extension String metadata
community Detected community name
layer Architecture layer from .aura/arch-rules.json
archviolations Number of new (non-baselined) violations where the file is the source
isorphan, isdead, incycle, ispinned, dirty, hasnote, stalenote, isarchviolator Boolean flags (dirty = uncommitted git changes, hasnote = annotated file, isarchviolator = file imports a forbidden layer)

Operators: ==, !=, >, <, >=, <=, ~ (regex), !~, in [ ... ], not in [ ... ], contains, startswith, endswith, between … and …, plus AND / OR / NOT and parentheses.

Comparing fields: a bare identifier that names a field compares two metrics of the same file — fanIn > fanOut, complexity >= cognitive. Anything else stays a literal, so language == typescript is unchanged; quote it (language == "fanIn") to force a literal. The string operators take a word or a quoted string: path contains "src/", name startswith test_, path endswith .css.

Aggregates: under the match count the palette sums what the matched set contains — Σ loc, ⌀ complexity, max fanIn.

Examples:

  • language in [typescript, python]
  • fanIn > 10 AND complexity > 20
  • isorphan
  • dirty AND complexity > 20 — files being edited right now
  • cochange > 0.6 — strongly coupled files (run Time Travel first)
  • hasnote — every annotated file
  • layer == domain AND archviolations > 0 — layer-pure violations, ranked by count
  • isarchviolator — every file that imports a forbidden layer
  • path ~ /src\/.*/

Modes: Highlight (dim non-matching files), Filter (hide non-matching files), Select (multi-select matching files). Switching modes is safe by design: leaving Select releases the files it had multi-selected before the next mode paints, so a Filter query never lands on a graph the previous Select left dimmed.

Saved queries: press ⭐ to save the current expression under a name and 📚 to reopen the saved list (persisted in .aura/graph.db). A saved query is an expression, not a mode: clicking a row never switches Highlight / Filter / Select — the mode you are in stays.

Remembered: the palette is part of the view state — it reopens open or closed exactly as you left it, with its expression and mode, and the graph comes back filtered/highlighted the same way. It belongs to the tabs that list files — the 3D graph and the Table — and nowhere else: switching to any other view hides it (the intent is kept) and coming back brings it up again.

One expression, two views: the Table tab carries the same 🔍 Query button. Apply complexity between 20 and 40 and the table lists exactly those rows, sortable by any column, and 📤 Export writes the rows on screen — the export can no longer disagree with the view. The mode (Highlight / Filter / Select) only changes how the graph shows the matches; a table always lists them.

File Explorer Panel

Toggle a tree-view panel showing all files organized by directory. Click a file to select it in the graph.

Directory filtering: Each directory has a checkbox to show/hide its files in the graph. Use the All / None buttons at the top for batch selection. Directories are checked by default.

Filter by Language

Toggle language buttons in the filter bar to show/hide files by type. Each button carries its file count (TS 42), so the top bar only keeps the two totals — overall files and links. Multiple languages can be active simultaneously.

Adjustable Controls

Slider Effect
Node Size Scale the visual radius of all nodes
Spread Adjust the repulsion force between nodes — the new spacing is settled synchronously (20 ticks after a 160 ms debounce), so the graph jumps straight to its new shape instead of drifting for a second
Depth (1–5) Set how many neighbor levels to show when pinning focus

The layout never moves on its own. A filter change does not start a live settle: files that come back are seeded next to their neighbours (or grouped by folder when they have none), and a batch of 5+ re-admitted files gets a synchronous 10–30 tick warmup inside the data digest — before the first paint, so nothing animates. The trade-off is explicit: re-showing a type may rearrange the graph, and warps/breadcrumbs still replay their stored pose.

No automatic zoom-to-fit. The camera keeps the pose it starts with; Aura used to pull back 1.5 s after loading and everybody zoomed straight back in. Use Recenter (F) or click the background when you actually want the whole graph framed.

In-App Settings ⚙️

The ⚙️ button in the tab bar (next to 🔍 Query) opens an in-app settings modal — no need to dig into VS Code settings. The controls are grouped: Graph & links, Camera & selection, Pilot & gamepad, Risk & analysis, Editors & hints. The bloom sliders only show when the selected-node effect is bloom.

Control Effect
Risk history window 30 / 90 / 365 days of git history — drives the Risk Map, the status bar and hotspots
Mouse rotation speed 1 → 5 slider — how fast dragging rotates the 3D view
Link style Straight or curved dependency edges (+ curvature amount)
Selected node effect Glow halo or bloom post-processing (+ intensity / radius / threshold)
Flight speed / smoothing Pilot mode base speed (scene-scaled) and acceleration damping
Mouse look sensitivity / invert Y Pilot mode mouse-look feel (also scales the gamepad stick look rate)
Gamepad in pilot mode Fly with a DualSense/Xbox pad (W3C standard mapping) — on by default, ignored outside pilot mode
auraVisualizer.codeLens true ⟡ focus · flow · impact CodeLens above the symbols of analyzed files
auraVisualizer.agentContext Refresh .aura/HOTSPOTS.md, .aura/hotspots.json and the aura:begin block after every analysis (off — the command is enough until you opt in)
auraVisualizer.edgeClickSelect Clicking an edge also multi-selects both endpoints (true); turn off to only frame and glow the edge
auraVisualizer.breadcrumbs Record visited places on the navigation trail over the graph (off by default)
auraVisualizer.focusDistance Distance (scene units, 40–400, default 120) the camera stops at when focusing a file — click, search jump, follow editor
Follow editor Fly the camera to the file of the active editor (👁 toolbar toggle)
Auto-refresh on save Re-analyze changed files automatically

Changes apply instantly and are saved to your workspace settings. The footer link opens the full auraVisualizer.* list.

Incremental Updates

When autoRefresh is enabled, the graph updates automatically whenever you save a file — no manual re-scan needed. Only the changed file is re-parsed and its edges recalculated (O(1) instead of O(N)).

Instant startup: The graph is persisted to a local SQLite database (.aura/graph.db). On next launch, the cached graph loads instantly; a fingerprint (git HEAD + settings + parser version + file size/mtime list) skips the analysis entirely when nothing changed, and otherwise re-parses only the modified files before sending a delta update.

Function Call Labels

In the detail panel, dependency links of type function-call display the actual function name (e.g. helper()) next to the target file. A green ×N badge shows when multiple distinct call sites exist between the same pair of files.

In the 3D Graph, function-call edges have logarithmic width scaled to call count, and hovering an edge displays a tooltip listing the top 5 caller → callee function pairs.

For C/C++ projects, function-call links are only created between files connected via #include — preventing false positives between unrelated files that happen to define functions with the same name.

Documentation in the Graph

Markdown, plain-text and reStructuredText files (.md, .markdown, .txt, .rst) are first-class nodes in the graph:

  • Dotted doc-reference edges automatically connect each doc file to the code files it mentions — detected from symbol names (functions, classes, methods, exports) and basename references like extension.ts. Doc edges do not count toward fan-in / fan-out, so hotspot metrics stay clean.
  • A 📄 Docs filter button in the toolbar toggles documentation nodes on / off (hidden by default to keep the structural view focused); its colour dot is the exact colour of the doc nodes (#b0bec5) — including in the Architecture layers and Communities heatmaps, where docs have no value and used to be dimmed to near-black
  • Doc content is chunked by heading and indexed in a local FTS full-text index — exposed to AI assistants through the search_docs MCP tool.

Symbols in the File Explorer

Files in the side Explorer panel that contain functions or methods show a chevron to their left. Click it to reveal an indented list of every function/method in the file (sorted by line number). Click any function to open the file in the editor and jump to that exact line.

Each function row also carries two action buttons: ▶ traces its outgoing call chain across files, and ⑂ opens its function flowchart — the branching structure of the function rendered as an explorable SVG diagram.

In the detail panel, functions supported by the static metric engine (JS/TS/TSX, Python, C/C++, Java, Go, Rust, Kotlin, Swift, C#, PHP, Lua and Bash) show a cog N · MI N chip: Sonar-style cognitive complexity and Maintainability Index, with cyclomatic complexity, Halstead volume and function length in the tooltip.

This turns the Explorer into a fast outline / go-to-symbol navigator across your whole project.

Tabbed Views

Switch between 11 visualization tabs for different perspectives on your codebase:

Tab Description
✦ 3D Graph Interactive 3D force-directed dependency graph (default)
🏙️ City The same graph as a 2.5D city — one building per file, height = the metric you pick, footprint = its size, districts = its folder. Click to read, double-click to open, click a plate to drill in
🗺️ Treemap Files nested by directory, sized by LOC or complexity, colored by metric. Click to zoom into subdirectories, breadcrumb navigation to zoom out.
🗑️ Matrix N×N Dependency Structure Matrix (DSM). Rows and columns are files; a colored cell means a dependency exists. Red cells with ↺ indicate circular dependencies. Group by directory, language, architecture layer, or community — a forbidden layer dependency is a red cell with ✖.
🎵 Chord Chord diagram showing dependency flows between groups (directories, languages, architecture layers, or communities). Ribbon thickness reflects flow volume. Hover to highlight a group and its connections.
📊 Metrics Dashboard with bar charts: LOC, complexity, fan-in, fan-out by language and top files.
📈 Timeline Line chart showing metric evolution over git history (LOC, file count, avg complexity, total complexity). Requires Time Travel scan.
📋 Table Sortable, filterable spreadsheet of all files with LOC, complexity, cognitive max, fan-in/out, symbols, layer, and folder. With a query applied it lists exactly its matches — sort them, then export those rows as CSV.
🛡️ Risk Codebase risk dashboard — health score, risk distribution, churn × complexity matrix, bus factor, and an exportable report
🏛️ Architecture Layer rules — violations by rule, Ca/Ce/instability per layer, aggregated cycles, unlayered files, baseline and Markdown export
🔗 Co-change Temporal co-change — files that change together in git commits without a direct dependency (Jaccard score, support, virtual links)

All tabs share the same live data and update when the graph is refreshed.

Every list of files behaves the same way. In Treemap, Matrix, Metrics (top-file bars), Table, Risk and Co-change, a left click selects the file — the row lights up and the graph remembers it — and a right click opens a menu with the three ways out: 📄 Open source (the editor), ✦ 3D Graph (switches tab and selects the node) and 🏙️ City (switches tab and selects its building). Nothing opens on a plain click, so a list can be read, sorted and compared without leaving the view; Esc or a click elsewhere closes the menu. The 🏙️ City applies the same rule to its buildings: right-click one for the same menu, with 🗺️ Treemap as the third entry (the City is where you already are).


Getting Started

  1. Install the extension from the VS Code Marketplace (or load the .vsix)
  2. Open a project folder in VS Code
  3. Press Ctrl+Shift+A (or Cmd+Shift+A on Mac)
  4. Explore your codebase in 3D

You can also open the visualizer from the Aura icon in the Activity Bar or via the Command Palette → Aura: Visualize Codebase.

Multi-root windows — Aura analyses the first folder of the workspace only. Files that belong to another folder of the same window are not part of the graph, so the 3D view, the hotspots and the status bar badges all cover that first folder.


Commands

Command Shortcut Description
Aura: Visualize Codebase Ctrl+Shift+A Open the 3D visualization
Aura: Refresh Visualization — Re-analyze the workspace
Aura: Focus Current File — Highlight the active editor file in the graph
Aura: Blast Radius — Show blast radius for the active file
Aura: Export Graph for AI — AI context export — Markdown or JSON, selectable sections and token budget
Aura: Export Graph as PNG — Capture the 3D graph at ×1/×2/×4
Aura: Export Architecture Report — Markdown + Mermaid architecture report
Aura: Export Architecture Report with AI Narrative — Same report plus an AI-written architecture explanation
Aura: Export Metrics (CSV/JSON) — Per-file LOC, complexity, cognitive max, fan-in/out, churn, authors and risk
Aura: Create or Open Architecture Rules — Seed .aura/arch-rules.json from top-level src/ folders and open it
Aura: Baseline Architecture Violations — Freeze current violations in .aura/arch-baseline.json
Aura: Reset Architecture Baseline — Clear the baseline — every violation alerts again
Aura: Show Risk Map — Open the Risk tab, or reveal the clicked hotspot
Aura: Show Architecture — Open the Architecture tab
Aura: Copy View Link — Copy a vscode:// link that reopens this exact view (tab, filters, camera, query)
Aura: Find Symbol… — QuickPick over every indexed symbol, with kind chips → graph focus + explosion + ripple
Aura: Review Current Branch — Diff the branch against its merge-base: touched files, ±lines, Δcomplexity, blast and compare

Keyboard Shortcuts (in graph)

Key Action
Ctrl+K Open the query palette (the match set narrows every view)
F Fit to view / recenter
L Toggle node labels
G Toggle directory groups
H Cycle heatmap modes
P Toggle path-finding mode
D Toggle DAG layout
O Highlight orphan files
X Toggle dead code visualization
C Toggle circular dependencies
1–5 Set pinned focus depth
V Toggle timeline compare mode (dual slider)
I Toggle timeline impact cascade
Space Toggle pilot mode (free flight)
Alt+Shift+1–9 Fly to the warp point on that quick slot
← → Timeline: previous / next commit
Backspace or Alt+← Navigation trail: back to the previous place
Escape Reset all — clear selections, heatmaps, timeline

AI Integration

Aura includes a built-in MCP server (Model Context Protocol) and a Graph Database so AI assistants can query your codebase structure programmatically.

Graph Database

Every analysis is persisted to a local SQLite database (.aura/graph.db via sql.js/WASM). This enables fast structural queries without re-parsing.

Chat participant @aura

Open VS Code Chat and mention @aura to ask about architecture, hotspots, impact or dependencies. Aura grounds every answer in the analyzed graph and exposes the same deterministic tools as the MCP server and the Language Model tools.

  • Slash commands: /explain, /impact, /path, /hotspots, /query
  • Answers link files directly and offer actions: Focus in Aura, Apply Aura Query, Open Risk, Open Aura
  • Ask Aura buttons live directly in the UI: file detail (Explain / Impact / Refactor plan / Tests first), clusters, communities, layers, the Risk dashboard and the explorer context menu
  • VS Code Chat is the only conversational surface: the old in-panel assistant (✨ button) was removed in favor of @aura

Export an AI context

Use 📤 Export (or Aura: Export Graph for AI) to give an LLM a focused view of the codebase:

  • Format: Markdown briefing or structured JSON
  • Sections: modules + inter-module dependencies, contracts (exports/interfaces/header declarations), hotspots, cycles and dead code
  • Budget: 2k / 4k / 8k / 16k tokens or no limit — estimated at ~4 characters per token
  • Truncation is explicit: omitted items/sections are reported, never silently cut
  • Save to a file or copy directly into the prompt

MCP Server

The MCP server exposes your codebase graph to AI tools via stdio transport. It registers automatically in .vscode/mcp.json on first run.

Resources:

URI Description
aura://overview Architecture overview — file counts, LOC, complexity by language
aura://nodes All files with full metrics
aura://node/{id} Detail for a specific file — symbols, dependencies, dependents

Tools (22):

Tool Parameters Description
build — Readiness check — analysis timestamp + age, file/link counts, commit analysed vs current HEAD, stale flag (null when undecidable) and the reason. Call it before trusting any metric.
explain_file file One-call file briefing — metrics, risk score with reasons, cycles, dead/unused symbols, incoming/outgoing call sites, dependencies/dependents, heritage, co-change partners and the architectural community.
hotspots_in_changes base, limit Risk inside the change set — working-tree diff by default, branch vs merge base when base is given; each row carries +/- and its risk reasons, riskiest first.
list_repositories — Which repo/worktree is served — root, database path, analysis age, HEAD, staleness and every git worktree with its branch.
find_dependencies file, depth Transitive dependency tree + the direct call_sites behind each edge
find_dependents file, depth Impact analysis — blast radius with risk levels + the direct call_sites behind each edge
find_path from, to Shortest dependency path between two files
find_cycles — Circular dependencies — file-level cycles plus function-level symbol_cycles (recursion/mutual recursion with call lines)
find_orphan_files limit Files that nothing imports
find_dead_code — Unused exports across the codebase; framework/test exemptions are returned separately with their reasons
find_unused_functions file, include_methods Functions/methods never called anywhere, with their line
get_hotspots limit, sort_by, window_days At-risk files ranked by the repository-relative risk score (percentile-based) with written reasons; raw metric sorts still available via sort_by
get_largest_files limit Largest files by lines of code
get_cochange limit, min_score Temporal-coupling pairs — files changing together without a direct dependency (Jaccard score)
search_symbols query, kind Find functions, classes, exports by name
find_heritage file Inheritance and implementation relationships (extends/implements)
get_architecture — High-level overview by language
get_communities — Code-only architectural modules from the shared Louvain snapshot; hub-path/user labels, documentation excluded
search_docs query, limit Full-text search across project documentation (Markdown / .txt / .rst) — returns ranked chunks with file path, section heading, and excerpt
resolve_context task, limit Ranked list of files most relevant to a natural-language task (deterministic, no LLM)
generate_documentation hotspot_limit Full documentation payload: overview, modules, hotspots, cycles, dead code, inter-module links
get_architecture_violations limit, include_baselined Evaluate .aura/arch-rules.json — new deny/slice violations, per-layer Ca/Ce/instability and aggregated layer cycles; documentation excluded

Every payload is anchored. As soon as a tool knows a line, the entry carries file, line and a ready-to-cite anchor field ("src/risk/risk-core.ts:142") — nothing to concatenate on the agent side. That covers search_symbols, search_docs, find_dead_code, find_unused_functions, find_heritage, resolve_context and explain_file. find_dependencies and find_dependents also return the direct call_sites (from, to, line, anchor) behind each edge, so the agent jumps straight to the call instead of grepping for it.

The server ships operating instructions. On initialize, Aura returns an instructions block telling the agent to call build first, prefer the indexed tools over shell git/grep, quote the anchors, and say so when the graph is stale — so the workflow survives without any per-project prompt.


Settings

All settings live under auraVisualizer.* — the most common ones are also editable in-app via the ⚙️ Settings button.

Setting Default Description
auraVisualizer.excludePaths ["node_modules", ".git", "dist", "build", "out", "__pycache__"] Directories to exclude from analysis
auraVisualizer.maxFiles 500 Maximum number of files to analyze
auraVisualizer.autoRefresh true Auto-refresh on file save
auraVisualizer.statusBar true Show Aura's status bar badges — file/link counter, active-file risk, ⚠ N hotspots in your changes, architecture violations (one switch for all of them)
auraVisualizer.reviewBase "" Branch compared by Aura: Review Current Branch — empty = auto-detect main, then master
auraVisualizer.transitiveDepth 5 Import hops followed by Transitive imports / dependents in the detail panel and by the dependency MCP tools (1–10)
auraVisualizer.followEditor true Fly the 3D camera to the active editor file; manual camera movement pauses following until the 👁 toolbar button is clicked again
auraVisualizer.riskWindow 90 Git history window (30 / 90 / 365 days) used by the Risk Map, the status bar and get_hotspots
auraVisualizer.riskCentrality false Use the PageRank centrality percentile instead of fan-in in the risk score
auraVisualizer.complexityTrendThreshold 0.5 Complexity points per 30 days that flag a file as degrading in the Trend column / Risk dashboard
auraVisualizer.rotateSpeed 1 Rotation speed when dragging the 3D graph (1–5, 5 = fastest)
auraVisualizer.linkStyle "straight" Edge style in the 3D graph (straight / curved)
auraVisualizer.linkCurvature 0.25 Curvature amount when linkStyle is curved (0–1)
auraVisualizer.selectedNodeEffect "glow" Selected-node highlight — glow halo or bloom post-processing
auraVisualizer.bloomStrength / bloomRadius / bloomThreshold 1.2 / 0.6 / 0.0 Bloom tuning when selectedNodeEffect is bloom

Edge Types

Type Color Source
include Light blue C #include "file.h"
system-include Light blue (dim) C #include <stdlib.h>
import Yellow JS/TS import
require Yellow (dim) CommonJS require()
dynamic-import Yellow (faint) import() expressions
function-call Green Cross-file function calls (C, C++, JS/TS, Python, Java, Go, Rust, Kotlin, Ruby, Swift, C#, PHP, Lua)
global-use Cyan Reads of a window.X / globalThis.X namespace defined in another file (AuraSprites.ripple, window.AuraTimeline.state()) — confidence 0.6
extends Pink Class/struct inheritance
implements Purple Interface / trait implementation
script Orange HTML <script src> / Vue <script src>
stylesheet Purple HTML <link rel="stylesheet">
css-import Purple (dim) CSS @import
source Green (dim) Shell source file.sh / . file.sh
css-url Purple (faint) CSS url() references
doc-reference Slate (thin) Mentions of code symbols / filenames inside .md / .txt / .rst files

global-use — the runtime half of a classic <script> architecture. Files loaded as plain scripts (no import, no module system) expose a namespace and consume each other through it: sprites.js defines window.AuraSprites, app.js calls AuraSprites.ripple(…). Pairing the definitions with their reads (both read from the Tree-sitter AST, so comments and strings never count) turns those invisible couplings into real edges: the webview's scripts stop being isolated leaves and become one connected module, where every file that reads AuraSprites holds an edge that would break if sprites.js changed. The script edge says loaded by, global-use says used by. The pair is what makes blast radius and fan-in honest for script-tag architectures. Confidence is 0.6 (the namespace is unique in the repository, but any script could overwrite it at runtime), so the Edge confidence slider hides them above 0.6. Incremental re-analysis keeps the index up to date: a changed file re-registers the namespaces it defines and re-emits its own edges.


License

MIT

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft