✦ Aura Visualizer
Visualize your codebase in 3D directly inside VS Code
Interactive dependency graph • Force-directed layout • AI-ready
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.
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.
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
- Install the extension from the VS Code Marketplace (or load the
.vsix)
- Open a project folder in VS Code
- Press
Ctrl+Shift+A (or Cmd+Shift+A on Mac)
- 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
| |