nervegraph

Obsidian Graph View, but for source code. One command scans the project, another opens an interactive relationship map in the browser.

Liquid · JavaScript · TypeScript · Vue/Svelte/Astro · HTML · CSS · Python · Ruby · Rust · Go · PHP · Java/Kotlin · C/C++ · Markdown · Shell · Terraform

npx nervegraph scan     # → .nervegraph/graph.json
npx nervegraph view     # → http://localhost:4210

nervegraph scanning its own repo. Selecting src/graph/build.ts shows its 4 dependents and 8 dependencies, each with the exact import line.

---

Install

Nothing to install — npx runs it straight from npm:

npx nervegraph scan
npx nervegraph view

Or install it properly:

npm install -g nervegraph     # global, gives you the `nerve` binary
nerve scan
nerve view

npm install -D nervegraph     # per-project
npx nerve scan

Requires Node ≥ 22.6.

---

Usage

nerve scan  [path] [flags]    # writes .nervegraph/graph.json
nerve view         [flags]    # serves the interactive map
nerve query <file> [flags]    # what uses this file, and what it uses
nerve check        [flags]    # fail the build when the graph breaks a budget
nerve diff <a> [b] [flags]    # what changed structurally between two graphs
nerve export       [flags]    # the graph as mermaid or dot text
nerve mcp          [flags]    # serve the graph to an agent over MCP (stdio)

nerve scan

Flag	Default	What it does
--profile <name>	auto	shopify, js, poly, or auto detection
--watch	off	re-scan on change; an open viewer reloads itself
--out <dir>	.nervegraph	Where graph.json is written
--ignore <glob>	—	Extra ignore pattern; repeatable
--no-gitignore	off	Don't read .gitignore
--classes	off	Also collect CSS/HTML class names (noisy)
--pretty	off	Indent graph.json — bigger, but diffable by hand
--json	off	Machine-readable summary on stdout
--quiet	off	Suppress the report

.gitignore and .nervegraphignore are respected by default, and node_modules, dist, build, vendor, coverage and minified files are always skipped.

nerve view

Flag	Default	What it does
--port <n>	4210	Port to serve on (probes upward if taken)
--graph <path>	.nervegraph/graph.json	Which graph to open
--no-open	off	Don't launch a browser

In the viewer: click a node for its dependents and dependencies, / or Ctrl+K to search, and use the sidebar to filter by language, relation type, or to isolate orphans, high-risk files and broken links. ? shows the rest — colour and size modes, the issues panel (i), shift-click to trace the path between two files, and the focus controls.

nerve query

Flag	Default	What it does
--json	off	The card as JSON and nothing else — pipe-safe
--depth <n>	—	Also list files within n hops
--orphans	off	List every file nothing references
--missing	off	List referenced files that aren't on disk
--unresolved	off	List references static analysis couldn't follow
--risk <level>	—	List files at low, medium or high risk
--dead-exports	off	List exports nothing imports
--duplicates	off	List groups of byte-identical files
--cycles	off	List dependency cycles
--packages	off	Fold the graph up to one node per package (monorepos)
--graph <path>	.nervegraph/graph.json	Which graph to read

$ nerve query src/graph/types.ts
src/graph/types.ts
  typescript javascript · 122 loc · risk high
  34 dependents (50 transitive) · 0 dependencies

nerve check

The same artifact as a gate. Nothing fails unless you ask for it, except a reference to a file that isn't on disk:

nerve scan --quiet && nerve check --max-cycles 0 --no-duplicates
# exit code 7 when a budget is broken, 0 when every budget is met

Flag	What it means
--max-cycles <n>	At most n dependency cycles
--max-unresolved <n>	At most n references static analysis couldn't follow
--max-orphans <n>	At most n files nothing references
--allow-missing	Tolerate references to files that aren't on disk
--no-dead-exports	Fail if any export is unused
--no-duplicates	Fail if any two files are byte-identical
--rules <file>	Layer rules; .nervegraph/rules.json is picked up automatically

Layer rules are yours to write — the tool only checks what you declared:

[
  { "name": "ui must not reach the database", "from": "src/ui/**", "deny": "src/db/**" },
  { "from": "src/core/**", "allow": "src/core/**" }
]

nerve diff and nerve export

nerve diff old-graph.json                  # against .nervegraph/graph.json
nerve export --format mermaid --focus src/graph/build.ts --depth 1
nerve export --format dot --out graph.dot

diff names new and removed files and edges, cycles introduced or resolved, files that became orphans, and files whose risk went up — the structural half of a code review. export writes the map as text, so a diagram can live in a README or an ADR and be diffed like code.

Typical run

cd some-project
npx nervegraph scan          # 98 files · 114 edges
npx nervegraph view          # → http://localhost:4210

For AI agents

graph.json is plain, sorted, deterministic JSON, so an agent (Claude Code, Cursor) can read the dependency map instead of grepping the whole repo:

nerve query snippets/product-card.liquid --json

usedBy lists what breaks if the file changes, transitiveDependents is the full blast radius, and stale: true means the file changed since the scan — run nerve scan first. The whole map is also readable directly:

nerve scan --quiet && cat .nervegraph/graph.json

Keep it fresh while working: nerve scan --watch in one terminal, nerve view in another — the map reloads itself on every re-scan.

Agents that speak MCP can skip the shell entirely:

{ "mcpServers": { "nervegraph": { "command": "npx", "args": ["nervegraph", "mcp"] } } }

It exposes two tools — nervegraph_query (one file's dependents, dependencies, risk and blast radius) and nervegraph_list (orphans, missing files, high-risk files, unused exports, duplicates, cycles). The graph is re-read on every call, so nerve scan --watch keeps the agent current.

---

Languages

Language	Extensions	What becomes an edge
Liquid	.liquid	render, include, section, sections, content_for, asset_url, t
JavaScript / TypeScript	.js .mjs .cjs .jsx .ts .tsx .mts .cts	import, export … from, import(), require()
HTML	.html .htm	<script src>, <link href>, <img>/<source>/<iframe>/… src
CSS	.css .scss .sass .less	@import, @use, url()
Python	.py .pyi	import x, from x import y, relative from .x import y
Ruby	.rb .rake .gemspec	require, require_relative
Rust	.rs	mod x; (the declarations that pull files into the crate)
Vue / Svelte / Astro	.vue .svelte .astro	the <script> imports, <style> @use/url(), and template src attributes
Go	.go	import "…" inside the repo's own module (from go.mod)
PHP	.php .phtml	require/include, and use through composer's PSR-4 map
Java / Kotlin	.java .kt .kts	import a.b.C under the Maven/Gradle source root
C / C++	.c .h .cc .cpp .hpp …	#include "x.h" (angle-bracket includes are external)
Markdown	.md .mdx	links and images pointing at project files
Shell	.sh .bash .zsh	source x.sh / . x.sh
Terraform	.tf .tfvars	module { source = "./…" }
Shopify JSON	templates/*.json, sections/*.json	sections.*.type
Web components	any markup + JS	<product-form> ↔ customElements.define('product-form', …)

Maturity

Breadth without measured accuracy is how a dependency graph quietly starts lying, so each language carries a label rather than an implied promise:

Level	Languages	What it means
verified	Liquid, JavaScript / TypeScript, HTML, CSS, Shopify JSON	Exercised against real projects; scanner and resolver both covered by tests
experimental	Python, Ruby, Rust, Go, PHP, Java / Kotlin, C / C++, Vue / Svelte / Astro, Markdown, Shell, Terraform	Covered by unit tests on fixtures, not yet measured on a large real codebase — expect gaps rather than wrong edges

A language moves to verified when its unresolved share has been measured on a real repository, not before.

Third-party references stay out of the graph: import requests, require 'json' and a CDN <script src> are reported as external, not as broken links. A reference that must be a project file — a relative Python import, a require_relative, a mod declaration — and isn't there becomes a missing node, which is the point: that's a broken link in production.

Known gaps

Deliberate, and cheaper to state than to hide:

• Rust use paths are not followed. mod declarations already define the file graph; use is item-level and would need full name resolution for zero extra nodes.
• Rails autoloading is invisible. Zeitwerk resolves User → app/models/user.rb with no require, so a Rails app's graph is thinner than its real coupling.
• Python docstrings can produce a phantom import if a line inside one starts with import x.
• ERB <%= %> inside an HTML attribute is skipped, because the > in %> ends the tag match. .html.erb isn't a scanned extension.
• A Go import resolves to one file of the package, not to all of them — the package's own <name>.go if it exists, otherwise its first source. Nodes are files, and a package is a directory.
• Java's same-package references are invisible, because they need no import; only cross-package coupling shows up.
• import a.b.* and use App\{A, B} are skipped rather than expanded to an arbitrary member of the package.
• Aliases are resolved from a single root config. tsconfig.json extends chains and per-package tsconfigs in a monorepo are not followed; workspace package names are.

---

Why

Open someone else's 60,000-line theme and understand its architecture in 10 seconds. See who uses a file before deleting it. See what breaks before editing a snippet.

A useful side effect: graph.json is machine-readable, so an AI agent (Claude Code, Cursor) can read the map instead of grepping the whole repo.

---

Key decisions (locked in)

Question	Decision	Why
Package name	nervegraph, binary nerve	Checked for availability on npm before publishing
Runtime	Node ≥ 22.6, TypeScript, ESM	Needs --experimental-strip-types to run TS sources directly
Argument parser	node:util → parseArgs	Stdlib, commander not needed
HTTP server	node:http	3 static files, express not needed
Liquid / HTML	Regex over tags, not a full AST	Reference tags are trivially regular
JS	es-module-lexer + regex for require	A full Babel AST is overkill for v0.1
CSS	postcss	Correctly extracts @import and selectors
Python, Ruby, Rust, Go, PHP, Java/Kotlin, C/C++, Markdown, Shell, Terraform	Line-oriented regex, zero dependencies	Import syntax in all of them is regular; a per-language parser would be one more dependency each for the same edges
Vue / Svelte / Astro	Split the file, reuse the HTML, JS and style passes	A SFC is three languages in one file, and all three scanners already exist
Visualization	force-graph (vasturiano), canvas	Drag, zoom, highlight, 5k+ nodes out of the box
Frontend framework	None. Vanilla JS + one HTML file	The detail panel is 150 lines of DOM
Storage	A single graph.json	SQLite at 100k+ nodes, not before