NodeGraph

Turn research papers into verifiable knowledge graphs with AI.

Point an AI agent (Claude Code, Codex, Cursor, Antigravity) at a PDF and it reads the paper and builds the whole graph itself, linking every claim back to the exact quote it came from. Prefer to build it yourself? Create a blank .nodegraph.json file and use the exact same interactive canvas by hand, no agent required.

Don't trust AI summaries. Verify every claim against the original paper in one click.

A Quick Look

An agent reading a paper it had never seen before and building the full nodegraph end to end, sped up — see Benchmark below for the real numbers

Getting there takes four steps:

1. Install NodeGraph from the VS Code Marketplace
2. Right-click your paper's folder and run NodeGraph: Copy Agent Spec to Workspace
3. Paste the generated .prompt/nodegraph/paper/english.md (or korean.md) into your agent, filling in the PDF's path
4. Open the finished .nodegraph.json

Perfect for

• Actually understanding a paper, not skimming it, by pulling the argument back into the ideas it converged from
• AI-assisted notes without the hallucination risk, since every claim traces back to the exact source quote
• Papers full of math and tables, where other note tools garble LaTeX inside a table and this one does not
• Sharing notes outside VS Code, since every graph exports to one self-contained HTML file, no extension needed

Motivation

Writing a paper means diverging first (exploring branches, dead ends, alternative framings), then converging that down into one clean, linear narrative. Actually dissecting a paper, understanding why each choice was made and not another, means running that process in reverse: pulling the converged text back apart into the diverged ideas it came from. That's naturally a node graph, not a linear document. That's what led to this mind-map-shaped approach in the first place.

Existing tools weren't quite it. Obsidian-style Markdown notes are great for linking ideas, but LaTeX doesn't render inside tables, a real blocker for papers whose comparison tables are full of notation. NodeGraph fuses what those tools do well into a single node: GFM tables, LaTeX (via KaTeX), and inline images all render together, in the same card.

It's also built around working with an agent rather than a mouse. Hand-placing every node as you read is tedious enough to break the flow of thought. Point an agent at the shipped .agent/nodegraph/SPEC.md instead, and (based on the question you're currently asking it) it can decide where in the graph a new idea belongs and write the node there itself, so a conversation with an agent turns directly into structure instead of stopping to file each note by hand.

An agent writing your notes raises an obvious concern: hallucination. That's exactly what the Original tag exists to guard against. Every claim can carry the exact source-text quote it's grounded in, and clicking it jumps straight into the source PDF and highlights the matching sentence, so you can verify the agent's claim against the paper in one click instead of trusting it blindly.

And since you don't always want to be inside VS Code to revisit your own notes, every graph exports to a single self-contained HTML file. Open it in any browser, no extension required.

Screenshots

Editor and exported HTML side by side — same layout, same content

Debug grid and Ctrl+F search
hop-level/main-topic-cluster boundaries, plus in-canvas search with matching nodes highlighted, in both the editor and the export

PDF quote-jump
right-click an original-text quote to open the source PDF and highlight the matching sentence (red box/arrow added for illustration)

Features

See FEATURES.md for the complete feature list, organized by Editing / Layout & wires / Find & focus / Images / Files & export.

Agent / AI Editing

Before pointing an AI agent at a project, run NodeGraph: Copy Agent Spec to Workspace once — it writes .agent/nodegraph/SPEC.md (copied from the extension bundle), .agent/nodegraph/ENVIRONMENT.md (freshly generated), and .prompt/nodegraph/{paper,lecture,code}/{korean,english}.md (ready-to-paste copies of the example prompts below, one pair per language — the paper prompt maps a paper PDF, the lecture prompt maps a lecture slide deck (see Mapping lecture slides below), the code prompt maps a codebase (see Mapping a codebase instead of a paper below)) into one folder, so the agent can read all of it like any other file without needing to know the extension's install path. Right-click the target folder in the Explorer and pick it from the context menu (this is the reliable way in a multi-root workspace, or to target one specific subfolder — it writes into exactly the folder you clicked, nowhere else); running it from the Command Palette instead targets the workspace's only folder, or prompts you to pick one if there are several. It's opt-in rather than automatic on purpose: .agent/nodegraph/SPEC.md is a large static doc identical across every install, and writing it into a folder automatically (the way .agent/nodegraph/ENVIRONMENT.md alone already does, silently, at every activation) would mean it could land in your own repo without you choosing that.

AI agents: read these two files before doing anything (both written by the command above, into the same folder):

1. .agent/nodegraph/SPEC.md — full JSON schema, syntax rules, and constraints
2. .agent/nodegraph/ENVIRONMENT.md — lists which Python libraries and CLI tools are installed on this machine (PDF reading, image processing, etc.)

Key rules from the spec:

• Backslashes in KaTeX must be doubled in JSON strings (\\frac, \\sqrt, \\text)
• Prefer $$...$$ display blocks for formulas — inline $...$ only for short in-sentence symbols
• Literal currency dollars must be escaped: \$4.28/GB (in JSON strings: \\$4.28/GB) — a bare $ opens an inline-math region
• When writing content in a non-English language, pair each key technical term with its original English form (see .agent/nodegraph/SPEC.md for the exact convention)
• The Killer Application is not limited to one — capture every genuinely remarkable contribution
• toggleItems[].content renders exactly like node.content — Markdown tables, KaTeX, and [[IMG:filename:WxH]] tokens all work inside toggles too
• Always update the "modified" timestamp after every edit

The file .agent/nodegraph/SPEC.md (included in the extension) is a machine-readable specification for AI agents. It documents the full JSON schema, ID conventions, KaTeX/Markdown syntax rules, rendering support per field, and a step-by-step workflow for generating a nodegraph from a PDF.

Five fully agent-built graphs ship with the extension, so you can open a finished result before building your own: demo/ex1 ("Attention Is All You Need"), demo/ex2 ("Point Transformer"), demo/ex3 ("Mooncake"), demo/ex4 ("3D Gaussian Splatting"), and demo/ex5 ("Mental Illness Terms and Hermeneutic Hijacking", a philosophy paper, not just CS/ML) — between them covering KaTeX formulas, Markdown tables, toggle sections, and deep question nodes.

Typical agent workflow:

1. Right-click the project folder in the Explorer and run NodeGraph: Copy Agent Spec to Workspace (one-time per folder). If you opened that folder itself as the workspace root, VS Code won't show a right-click menu on it directly, right-click the empty space below the file list instead
2. Tell your agent to read .agent/nodegraph/SPEC.md and .agent/nodegraph/ENVIRONMENT.md
3. Read or create the target .nodegraph.json
4. Edit the JSON directly
5. Click Reload in the toolbar to see the updated graph without closing/reopening the file

Example prompt

English | 한국어

After running NodeGraph: Copy Agent Spec to Workspace on the folder that holds your PDF (step 1 above), paste this into your agent — fill in the path and it does the rest: reads the spec, reads the paper, and builds the graph without further back-and-forth. The same command also writes this out as .prompt/nodegraph/paper/english.md (and a Korean version at .prompt/nodegraph/paper/korean.md) in that folder, so you can open the file directly instead of copying it from here.

PDF_ABSOLUTE_PATH = <PDF_ABSOLUTE_PATH>
PROJECT_FOLDER = dirname(PDF_ABSOLUTE_PATH)

PROJECT_FOLDER/.agent/nodegraph/SPEC.md and PROJECT_FOLDER/.agent/nodegraph/ENVIRONMENT.md
are already prepared for you — read both in full.

Based on the paper and those two files, briefly explain what kind of
nodegraph you can build from it, then build it.

**Shape.** Once the graph will carry **more than about 12 sub-nodes**, build it
hierarchical — see "Two shapes" in the spec. Below that, one level under the backbone
is fine and inventing intermediate nodes just to add depth is noise. When it applies:

- **At most 4 direct children on any node.** If a node needs a fifth child, invent
  an intermediate node that names what two of them have in common, and put them
  under that. Finding those names is most of the work.
- **Depth 3 or more.** A ~30-node graph should land near 5 / 12 / 9 / 4 across the
  levels, not 5 / 19 / 6.
- **Fill `children`** on every node that has any.
- **Each level answers a different question**: what is this / what are its parts /
  how does each part work / the case, the number, the exception.
- **A parent must read on its own.** Someone who stops at level 2 and never opens
  level 3 should still come away with a correct, coarser understanding.

Pick the backbone nodes with the spec's **kernel test** (Step 2): a kernel is something
the authors contributed that nobody else did. Find 4-8 of them and check the whole paper
reconstructs from that set. Sort everything else into SUPPORTING (real but standard — goes
below the kernel it supports) or non-kernel (gets no node at all). Then write the chain:
each kernel says which one it follows from and which it enables. A kernel that derives
from nothing and enables nothing is misclassified.

Write all node content in English.

Before you start, fix two things and tell me what you chose: (1) the canonical
reader for this graph — one plausible real person with only the minimum
background I'd expect; (2) the landmark, one sentence saying what this paper is
about and what the answer is. Record both in the result's top-level
`conventions` (see the spec's `conventions` section). That field is what lets
whoever adds a node later inherit these rules without re-reading the spec.

Write titles as claims that could turn out to be **wrong**, not as topics.
"Killer Application", "Why It's Needed", "Solution", "Results", "Conclusion" are
slot names, not titles — scanning the titles alone should explain the paper, and
a title that cannot be wrong carries no information.

When it's built, run one more shortening pass. Writing each node so it stands
alone is the habit that makes the whole graph slower to read than the source; a
node is a slide, not a document, and completeness is the path's job.

Quote page numbers (`p.N`) are the PDF's own page index counting from 1, not the number
printed on the paper — proceedings often differ by hundreds, and the viewer takes `p.N`
literally.

When you enumerate things, write a real markdown list with one item per line —
never `(1) … (2) … (3) …` run together inside a paragraph. Run-together
enumerations are the most common reason a node is hard to read.

When you are finished, run the verifier and paste its output:
`node <path-to-extension>/tools/verify-nodegraph.js PROJECT_FOLDER`
It re-reads every line range you cited and fails if a quote is not actually there, if an
`internal` link points at a node that does not exist, or if a node exceeds the fan-out cap.
Do not report success without running it.

Follow the spec exactly, save the result inside PROJECT_FOLDER, and run
end to end without asking me anything. When you are done, report the node count
at each depth and the largest fan-out in the graph.

Mapping lecture slides

Lecture slide decks are PDFs too, so the whole pipeline — quote-jump into the deck, image extraction, the interactive canvas — works on them unchanged. What changes is the shape of the graph: slides are figure-heavy with sparse text, so the agent follows the deck's own section structure as the backbone (overview/learning-goals first, then one node per section with its slide range), extracts figures generously, and quotes definitions verbatim from the slides. Right-clicking a quote jumps to the exact slide, since p.N maps 1:1 to slide numbers.

Run NodeGraph: Copy Agent Spec to Workspace on the folder holding the slides PDF, then paste .prompt/nodegraph/lecture/english.md (or .prompt/nodegraph/lecture/korean.md) into your agent, filling in the PDF's path.

Mapping a codebase instead of a paper

Point the same command at a codebase instead: run NodeGraph: Copy Agent Spec to Workspace on the project's root folder, then paste .prompt/nodegraph/code/english.md (or .prompt/nodegraph/code/korean.md) into your agent, filling in the project root's path. The agent walks the codebase instead of reading a PDF, and builds a graph around architecture, core implementation, and data/control flow instead of a paper's argument.

The key difference from the paper workflow: every node that points at real code carries a links entry of type code (e.g. src/foo/bar.ts:42-58), and clicking it jumps straight to that file and line range in the editor, no PDF-style search needed. Export the graph to standalone HTML and those same links resolve to GitHub blob URLs (.../blob/<commit>/path#L42-L58) if the project has a github.com remote, so the graph stays clickable outside the editor too.

PROJECT_ROOT_ABSOLUTE_PATH = <PROJECT_ROOT_ABSOLUTE_PATH>
PROJECT_FOLDER = PROJECT_ROOT_ABSOLUTE_PATH

PROJECT_FOLDER/.agent/nodegraph/SPEC.md and PROJECT_FOLDER/.agent/nodegraph/ENVIRONMENT.md
are already prepared for you — read both in full. Follow the "Code →
NodeGraph workflow" section specifically, not the PDF workflow.

Based on this codebase and those two files, briefly explain what kind of
nodegraph you can build from it, then build it.

Write all node content in English.

Follow the spec exactly, save the result inside PROJECT_FOLDER, and run
end to end without asking me anything. Tell me when done.

Benchmark — an agent read the PDF, planned, and wrote each nodegraph end to end with no manual cleanup, on papers it had never seen before. Tested with Claude Code; other agentic coding tools should work the same way, since all it needs is the plain-markdown spec and prompt in .agent/nodegraph/.prompt/nodegraph:

demo/ex5 is a philosophy paper, not CS/ML, included to show the workflow isn't limited to empirical papers with a methods/results structure — the agent used the same default node templates and it held up fine.

The demo/ex4 run above was recorded on v0.6.3, using NodeGraph: Copy Agent Spec to Workspace exactly as described in the four steps above — no README copy-pasting, no manual setup.

Watch the full demo/ex4 run (59s, no sound)

Mouse & Keyboard Controls

Installation

Install NodeGraph from the VS Code Marketplace, or search "NodeGraph" in VS Code's Extensions view (Ctrl+Shift+X) and click Install. A packaged .vsix (packages/nodegraph-<version>.vsix) is also available in this repo if you'd rather install that directly.

code --install-extension packages/nodegraph-<version>.vsix

npm install
node esbuild.js --production
npx vsce package -o packages/nodegraph-<version>.vsix

Node Content Syntax

Images are stored in a .<graphname>-imgs/ folder next to the JSON file.

File Format

{
  "version": "1.0.0",
  "title": "My Research Graph",
  "created": "2026-07-06T00:00:00.000Z",
  "modified": "2026-07-06T00:00:00.000Z",
  "source": {                             // optional — omit entirely if there's no source PDF
    "pdf": "paper.pdf",
    "authors": "Author et al.",
    "venue": "NeurIPS 2017",
    "doi": "arXiv:1706.03762",
    "pages": 15
  },
  "nodeTemplates": {
    "main_topic": { "label": "Main topic", "color": "#4B8BBE", "icon": "file-text", "shape": "sharp" },
    "question":   { "label": "Question",   "color": "#E5A835", "icon": "help-circle", "shape": "rounded" }
  },
  "nodes": [
    {
      "id": "node_001",
      "template": "main_topic",
      "title": "Introduction",
      "content": "Summary text with $\\LaTeX$ and\n[[IMG:figure1.png:500x300]]",
      "original": { "title": "Optional custom label", "text": "Exact quote from paper.", "location": "§1, p.1" },
      "toggleItems": [                    // optional — omit if the node has no toggle sections
        { "id": "toggle_001", "title": "Table 1", "content": "| Col | Val |\n|-----|-----|\n| A | 1 |", "expanded": false }
      ],
      "contentExpanded": true,
      "originalExpanded": false,
      "childrenExpanded": false,
      "position": { "x": 0, "y": 0 },
      "children": ["node_002"],
      "links": [],                        // { type: 'url'|'pdf'|'obsidian'|'internal', target, label }[]
      "fontSize": 14,                     // optional — per-node title font size override
      "nodeWidth": 432,                   // optional — persisted card width after a manual resize
      "nodeHeight": 220,                  // optional — persisted card height after a manual resize
      "nodeNaturalY": 0                   // optional — Y position as last set by dragging; leave this to the editor
    }
  ],
  "edges": [
    { "id": "edge_001", "source": "node_001", "target": "node_002", "type": "arrow", "label": "" },
    { "id": "edge_002", "source": "node_002", "target": "node_003", "type": "line", "label": "" }
  ],
  "viewport": { "x": 0, "y": 0, "zoom": 1 },
  "canvasImages": []                      // optional — floating images pasted onto the background, not into a node
}

Commands

Tech Stack

Privacy

NodeGraph does not collect, store, or transmit any data to external servers.

• Everything lives in the .nodegraph.json file and local image assets next to it — no accounts, no telemetry, no analytics
• The editor loads KaTeX from the extension's own bundled assets (no CDN, no network)
• The one exception: opening an exported HTML file in a browser loads KaTeX from a CDN, since that file is meant to be viewed outside VS Code — the editor itself never does this