Revelio for VS Code

Revelio answers the question every engineer asks before touching shared code: "what will break if I change this?"

It builds a structural dependency graph of every component, hook, selector, action, and context in your React codebase — and surfaces that graph directly inside VS Code. Hover any symbol for an instant blast-radius summary. Open the File Risk panel when you edit a file to see its direct consumers, relevant test files, and co-changed companions. No context-switching, no grep, no guessing.

Requirements

• Node.js >= 20
• @revelio-tools/revelio installed globally:

npm install -g @revelio-tools/revelio

The extension manages the revelio serve process for you — you never need to start it manually.

Quick start

1. Install this extension from the VS Code Marketplace
2. Open a React project — if there's no revelio.config.json yet, run revelio init in your terminal (auto-detects aliases from tsconfig / jest / vite)
3. Index the codebase once: run revelio build in your terminal (takes a few seconds on most repos; stores a revelio.db file)
4. Revelio starts automatically — the status bar shows Revelio: starting... then Revelio: ready (Nk)
5. Hover any component, hook, or selector to see its blast radius; open the File Risk panel on the left for file-level detail

Features

Hover tooltips

Hover any exported symbol to see its signature, risk tier, and direct dependent count. The tooltip resolves platform-variant siblings (.web.js ↔ .js) and HOC-wrapped exports (#default) automatically, so the count you see reflects every real consumer. Command links jump straight to an impact query or graph view.

File Risk panel

The sidebar panel that auto-populates when you switch to or save a source file:

• Risk badge (MINIMAL / LOW / MEDIUM / HIGH / CRITICAL) based on blast radius
• Direct consumers — ranked by actionability (components first, styled wrappers last), expandable with "Show all" when there are more than 12
• Test files to run — scanned from __tests__ / *.test.* siblings, with a one-click copy button
• Co-changed files — git history companions that tend to change together. Off by default (revelio.showCochange); once enabled, run Revelio: Build & Load Co-change Data once to populate this data — indexing alone doesn't compute it.

Focuses on the symbol under your cursor, updating as you move the caret.

Sidebar panels

Three panels in the Revelio activity bar:

D3 graph visualiser

Revelio: Show in Graph opens a full-panel D3 visualiser beside your code:

• Radial tree — queried symbol at centre, affected nodes radiate outward by depth, coloured by confidence tier
• Graph explorer — force-directed canvas of the whole codebase; filter by kind, drag nodes

CodeLens

"N dependents" shown above every exported symbol. Click to run an impact query inline. Off by default (revelio.codeLensEnabled) — disabled while the dependent counts it surfaces can disagree with the File Risk panel and Impact Query for the same symbol; see Troubleshooting. Enable it once that's resolved.

Claude Code MCP auto-registration

When Claude Code is detected, Revelio offers to register itself as an MCP server so AI queries can use the structural graph directly.

Claude Code integration

Claude Code reads MCP server definitions from a .mcp.json file at your project root — use Revelio: Register with Claude Code from the Command Palette to let the extension write this automatically. If auto-registration does not trigger, add Revelio manually to .mcp.json:

{
  "mcpServers": {
    "revelio": {
      "command": "revelio",
      "args": ["serve", "--stdio", "--config", "/absolute/path/to/your/repo/revelio.config.json"]
    }
  }
}

--config must be an absolute path — Claude Code can spawn the server from any working directory, and revelio serve only ever resolves revelio.config.json relative to its own process, never via an environment variable. Then restart Claude Code.

Settings reference

Troubleshooting

"Revelio: offline" in the status bar The server could not start. Check the Revelio Server Log output channel (click the status bar item). Most common causes: revelio not installed (npm install -g @revelio-tools/revelio), or no revelio.config.json in the project root (revelio init creates one).

"Install Now" notification appears The extension couldn't find the revelio binary. Click Install Now — it opens a terminal and runs npm install -g @revelio-tools/revelio for you.

"Build Now" / DB not found The index hasn't been built yet. Click Build Now or run revelio build in the terminal.

Native module error (better-sqlite3) Do not run npm rebuild better-sqlite3 — @revelio-tools/revelio ships a bundled prebuilt binary and never compiles from source. Instead, re-run its install script: npm run setup in the directory where it's installed (usually $(npm root -g)/@revelio-tools/revelio).

Hover tooltips show 0 dependents The index may be stale. Run revelio build or use Revelio: Rebuild Index from the Command Palette. If the count is still wrong for a HOC-wrapped component, the WRAPS edge may not be in the graph yet — a full rebuild resolves it.

Server crashes immediately Open Revelio: Show Server Log from the Command Palette and share the output when filing an issue.

CodeLens is off by default revelio.codeLensEnabled defaults to false. CodeLens shares the same hover resolution path that can disagree with the File Risk panel and Impact Query for the same symbol (a known issue being investigated); it's disabled until that's fixed, to avoid surfacing a possibly-wrong dependent count above your code. The File Risk panel and Impact Query are unaffected and remain the reliable source for risk/dependent counts. Re-enable the setting once the fix lands.

Telemetry

Revelio can optionally report anonymized error categories — one of a closed set: binary-not-found, index-not-built, server-spawn-failed, server-start-timeout, auth-token-missing, fetch-failed — and coarse activation health (whether the server started OK on this run, and which OS platform you're on) using VS Code's standard @vscode/extension-telemetry integration.

This is designed to close a specific gap: silent, environment-dependent failures (PATH-resolution issues, DNS quirks, missing binaries) are currently only visible in the Revelio Server Log output channel, so the maintainer has no way to know how often they occur in the wild until a user files an issue.

What is never sent: file paths, file names, symbol names, repo/project names, config file contents, query text, or any other code or project content. The reporting API only accepts a fixed, closed set of category constants and the OS platform string — there is no free-text field, by design (see src/utils/telemetry.ts).

How to opt out: this fully respects VS Code's global telemetry.telemetryLevel setting — set it to off (or disable telemetry in VS Code's onboarding) and Revelio sends nothing, full stop. On first activation (only once telemetry is actually enabled) Revelio shows a one-time notice explaining exactly what's collected before anything is ever sent; it never asks again.

Contributing

Issues and pull requests welcome at github.com/sipandey/revelio-vscode.

Licence

MIT