RAPTOR Tree Visualizer

View RAPTOR retrieval trees as a radial graph — in VS Code or as a standalone HTML page. Format-agnostic: it does not care which implementation built the tree.

Status: the standalone viewer is complete and verified against real data — format, validator, radial renderer, redaction, and adapters for the official implementation, for JSONL dumps and for a LlamaIndex persist directory. The VS Code extension opens *.raptor-tree.json, the official implementation's *.pkl and a LlamaIndex index folder, and runs from a clone with F5; it is not on the marketplace yet.

The bundled example, which is what you get when you open the page: 43 nodes about strawberries. A leaf is selected, so its path to the root is drawn in white and spelled out in the panel, above the node's full text.

Why this exists

You cannot judge a RAPTOR tree without looking at it. Clicking through a tree of ~3,900 nodes for the first time surfaced 92 summaries where the model had reviewed its own output instead of summarising — one of them at the top level, where it stands in for an entire subtree. Nothing short of seeing the tree finds that.

The problem: there is nothing to look at it with.

There is no RAPTOR file format

Every implementation stores something different, and two of three do not store the tree at all:

And no format-agnostic viewer

As of August 2026: viplismism/raptor ships a React dashboard, but wired to its own implementation. raggy (arXiv 2504.13587) supports RAPTOR as a backend but only ever shows retrieval results, never the tree. No VS Code extension for RAPTOR exists at all.

So the goal is not "draw a tree" — it is open any RAPTOR tree, whatever built it.

The format

One file, *.raptor-tree.json. It is the contract everything else hangs off:

{
  "raptorTreeVersion": 1,
  "source": "jsonl",
  "created": "2026-08-20T09:00:00Z",
  "trees": [{
    "name": "classic",
    "roots": ["classic:3:0"],   // a list: RAPTOR routinely leaves several
    "nodes": [{
      "id": "classic:2:0",
      "level": 2,               // 0 = leaf, the root has the highest level
      "text": "...",
      "children": ["classic:1:4"],
      "meta": { "title": "..." }   // free-form, adapter-specific
    }]
  }]
}

Embeddings are not included. They multiply file size and are not needed to draw anything — in our test data they are 74 MB of a 123 MB source. A useful side effect: the adapters need no numerical libraries.

Warnings, not refusals

The validator separates two severities, and the distinction carries the design:

• error — cannot be drawn. A cycle would loop the radial layout forever.
• warning — drawable but notable. Reported, blocks nothing.

Refusing to render at the first inconsistency would defeat the purpose, because the odd tree is the one you want to see. In one real tree, 17 of 3,558 leaves have no parent. As an error that tree would not open and you would never learn which 17. As a warning:

classic: 3908 nodes, 2 root(s), 3558 leaves, depth 3
  orphans: 17
  unreachable from roots: 17

warning: 17 node(s) have no parent and are not roots — they hang off nothing and
would be invisible.
  classic:0:1005230:0, classic:0:1005797:0, ...

Those 17 came from just 7 documents — whole documents had been skipped during clustering. That is the class of finding this tool is for.

examples/flawed.raptor-tree.json, which exists to be broken. Red marks the irregular edges: the child claimed by two parents, and the stub pointing at a node that was never there. The orphan sits at the top left with no edge at all — laid out anyway, because a node you cannot see is a node you cannot judge. Four warnings, zero errors, and the file opens.

Sharing a tree you cannot share

Your corpus is probably confidential, but the structure of the tree usually is not — and structure is what this tool renders and what a bug report is about. redact replaces every text, metadata value, id and tree name with synthetic stand-ins while keeping ids consistent, levels intact, child lists pointing at the same places, and text lengths the same:

node dist/cli.js redact private.raptor-tree.json shareable.raptor-tree.json

The result renders identically — the screenshots above were made this way — and reports the same validation issues, because hiding a finding would misrepresent the original. Ids are replaced by default: they are routinely built from source identifiers, and they are shown in the detail panel. --keep-ids turns that off when the ids carry nothing.

Nothing is shortened

A viewer you use to judge data has to be trusted not to change it. The jsonl adapter copies every text, child list, level and non-empty metadata field through untouched — verified against 18,965 real nodes: 42,661,810 characters in, 42,661,810 out, zero differences. Only two things are ever dropped, both empty: null/""/[] metadata values, and edges pointing at nodes that do not exist (reported as a warning, never silently).

Display is separate from data. Graph labels are truncated to fit the canvas — but the detail panel shows the full title and the full text, and issue reports list every affected node id rather than the first twenty. A truncated list of ids is worse than a long one: the ids are the part you can act on, and "and 40 more" cannot be looked up.

Usage

Requires Node 20+, and nothing else.

npm install && npm run build && npm test

Viewing a tree

npm run dev

Then open http://localhost:5173. With no arguments it loads the bundled strawberry example, so there is something to look at immediately — drop a *.raptor-tree.json anywhere on the page to replace it, or link straight to one with ?file=my-tree.raptor-tree.json.

A server is needed only because browsers refuse ES modules over file:// — nothing leaves your machine, and there is no build step beyond tsc.

Your trees should live outside the repository, since a real corpus is usually confidential and .gitignore is a thin defence against cp -r. The server takes several roots for exactly that:

node scripts/serve.js . ~/my-trees

The first root holding a matching file wins, so ?file=big.raptor-tree.json finds a tree in ~/my-trees while the page itself comes from the repository.

Drag to pan, wheel to zoom at the cursor, click to select, double-click to centre. Selecting a node highlights its path to the root; searching highlights hits in place, so you can see where in the tree a topic lives instead of reading a list of matches.

Labels are click targets, not just decoration. A leaf is a two-pixel dot and its label is two hundred pixels wide, so hit-testing checks the drawn label rectangles before the dots — otherwise clicking a name you can plainly read does nothing until you zoom right in.

In VS Code

The extension registers a custom editor for *.raptor-tree.json, so opening one shows the graph instead of raw JSON. The editor reads the file itself rather than going through a TextDocument, which VS Code refuses to load past 50 MB — a 51.6 MB tree opens. Saving the file from a text editor, a CLI run or anything else that rewrites it on disk redraws the graph.

A tree.pkl from the official implementation opens directly, with no conversion step: run RAPTOR: Open tree… from the command palette and pick it, or open the file and choose View: Reopen with → RAPTOR Tree (pickle). The bytes are read and turned into a tree in memory by the same opcode interpreter the CLI uses, so nothing in the file is executed and nothing is written to disk. The editor is offered rather than default, because .pkl is a generic extension and hijacking every pickle on the machine would be rude; a file that is not a RAPTOR tree is refused with the reader's own message, shown in the editor rather than thrown, so there is a way back out.

If you work with RAPTOR trees daily and want a double-click to be enough, claim .pkl on your own machine — either the Configure default editor for '*.pkl'… entry at the bottom of Reopen with, or in settings.json:

"workbench.editorAssociations": {
  "*.pkl": "raptorTree.pickle",
  "*.pickle": "raptorTree.pickle"
}

That overrides the manifest's priority, so a double-click goes straight to the tree with no "Open Anyway" step. Set it per workspace rather than per user if the machine also holds pickles that are not trees.

This also covers the save the patterns cannot: a custom editor is matched by filename, and RetrievalAugmentation.save() enforces no extension at all — the official demo writes demo/cinderella. RAPTOR: Open tree… passes the view type explicitly, so it opens a file with any name at all.

A LlamaIndex index needs its own way in, because it is a folder and a custom editor is always backed by a document: run RAPTOR: Open LlamaIndex index… and pick the directory RaptorRetriever.persist() wrote. It is converted in memory and opened in a panel of its own, so nothing is written next to your index. If the folder holds no docstore.json, or holds one with no RAPTOR metadata in it — a plain LlamaIndex index writes the same five files — you get a message naming what was missing instead of an empty graph.

To run it from a clone:

npm install     # builds both bundles via `prepare`

Then press F5 in VS Code. That opens a second window — the Extension Development Host — with the extension loaded; no installing and no packaging. Open any *.raptor-tree.json there, or run RAPTOR: Open tree…, RAPTOR: Open LlamaIndex index… or RAPTOR: Open example tree from the command palette.

To build an installable .vsix:

npm run package

The webview is a single bundled script under a strict CSP: default-src 'none', one script allowed by nonce, no network access of any kind. Nothing about a tree leaves the machine.

Searching

Searching does two things at once, and they answer different questions.

The graph marks every node containing a hit, which shows where in the hierarchy a term lives — and at which level of abstraction, since a summary matching a term is as visible as a leaf matching it.

A results column lists every occurrence, grouped by node, one line each with a few words of context — the way an editor lists hits by file rather than just naming the files.

Thirty-eight occurrences in twenty-nine nodes. The list answers "what does it say", the graph answers "where in the hierarchy is it" — including that the root itself matches, so the term is discussed at every level of abstraction.

Clicking a result opens that node and marks the occurrence green in its text; the other occurrences in the same node stay yellow. Enter and Shift+Enter step through the list without leaving the field.

The same search after clicking the first result. The node is selected, its path to the root is drawn in white, and the exact occurrence is green in the text on the right — the rest of the tree keeps its yellow markers, so you do not lose the overview by looking at a detail.

Two details worth knowing. The list is capped at 200 results, but the count is not — a search reporting "3,412 hits in 900 nodes · showing first 200" is telling the truth about both. And highlighting inside a node re-searches its text rather than filtering that capped list, so a node with fifty occurrences gets all fifty marked.

Queries shorter than two characters are ignored, and the search is debounced by 120 ms: one pass over a 12,000-node tree costs about 25 ms, which is enough to make a field feel like it is lagging behind the typing.

Zoomed in, labels wrap over up to five lines and are dropped when they would collide, so what stays on screen is readable.

How the layout is sized

Level is radius, and each subtree gets an arc proportional to its leaf count, so dense branches get more room. The ring gap is derived from the leaf count rather than fixed: the outer circumference has to seat every leaf. With a constant gap, 11,346 leaves land 0.3 units apart and merge into a solid line that no amount of zooming separates.

The opening zoom follows from the same number. If the whole tree fits with its leaves still a few pixels apart it is shown whole; otherwise the view starts about two rings deep, on the root. A large tree fitted to its extent is an unreadable ring, and a small tree zoomed to two rings is cropped for nothing.

A real tree of 3,908 nodes: two roots in the centre, then 28 and 320 summary nodes, and an outer ring of 3,558 leaves. The red mark at the top is 17 orphaned leaves hanging off nothing. Contents redacted with raptor-tree redact; the structure is untouched.

And at 12,485 nodes. Fully zoomed out, 1,035 mid-level nodes and 11,346 leaves become solid rings — that is what 12,000 nodes on a circle look like, and no layout hides it. Zooming in is what makes it readable, which is why the view does not start there.

Measured on 12,485 nodes and 12,477 edges at 1600×900 (Ryzen AI 7 PRO 350, integrated graphics), 60 frames per zoom level:

Hit-testing a pointer move over all 12,485 nodes costs 0.18 ms, by comparing in world space — converting the cursor once instead of projecting every node.

The budget for 60 fps is 16.7 ms per frame, so there is room to spare — no WebGL, and no spatial index. Culling is a plain loop over every node, because 12,000 visibility checks cost less than the structure that would avoid them. Edges and nodes are batched into one path per style; twelve thousand individual strokes would cost more than everything else combined.

One consequence worth knowing: edge opacity falls as the edge count rises. Thousands of half-transparent lines converging on one ring otherwise accumulate into a sheet brighter than the nodes drawn on top of it — the structure disappears exactly when there is most of it to see.

Labels are placed greedily against a collision list, ranked by selection, then level, then subtree size. Arc room alone is not enough to decide: it measures separation along the ring, but labels are wide, so two neighbours on a ring running horizontally across the view are far apart along the arc and still overlap.

Convert JSONL node dumps into the format, one tree per input file:

node dist/cli.js import trees.raptor-tree.json nodes.jsonl

Field names differ between projects, so remap them as needed, and name trees explicitly when the filenames collide:

node dist/cli.js import trees.raptor-tree.json \
  classic=data/classic/nodes.jsonl comfort=data/comfort/nodes.jsonl \
  --field=level=depth --field=children=child_ids --field=title=heading

Mapping title is worth doing when the source has a short label for each node: it becomes the node's name in the graph and in the CLI, and without it every label falls back to the first line of the node's text — which for a RAPTOR summary is a sentence, not a name.

Then check it:

node dist/cli.js validate trees.raptor-tree.json

A pickled tree needs no options at all — node indices become ids, levels are recovered by inverting layer_to_nodes (a pickled Node does not know its own layer), and embeddings are dropped:

node dist/cli.js import trees.raptor-tree.json tree.pkl

A LlamaIndex index is a whole directory rather than a file — whatever RaptorRetriever.persist() or RaptorPack.save() wrote — so that is the rule: an input that is a directory is read as one, since no other reader takes a directory.

node dist/cli.js import trees.raptor-tree.json ./raptor_index

Only docstore.json is read; the vector stores are embeddings, which this format never carries. There is no child list in the file at all, so every edge is inverted out of the parent_id on each node, and the roots are the nodes without one. A persist directory from a plain LlamaIndex index looks identical from the outside and is refused by name, saying which metadata was missing.

--strict makes warnings fail too. Exit codes: 0 ok, 1 check failed, 2 bad usage.

Adapters

The reader picks itself from the path — .pkl/.pickle for the official implementation, a directory for a LlamaIndex index, JSONL otherwise:

node dist/cli.js import trees.raptor-tree.json my-tree.pkl

Reading a pickle without executing it

pickle.load runs the code inside the file. That is not a flaw in anyone's code; it is what the format is for. Which makes it a bad foundation for a viewer, whose whole job is opening files you did not make.

So this project does not use Python's unpickler at all. src/adapters/pickle.ts is an opcode interpreter that walks the bytecode and builds plain JavaScript values. Where a real unpickler would call a function or construct a class — REDUCE, NEWOBJ, INST, BUILD — it produces an inert placeholder recording what was asked for and stops there. There is no registry of permitted classes, because nothing is ever looked up or invoked.

The difference from a restricted Unpickler with a find_class allow-list matters: that is a filter inside machinery built to execute code, so one gap in the list is remote code execution. Here there is nothing to gap.

test/fixtures/malicious.pkl keeps that claim honest. It reduces to os.system("echo PWNED > /tmp/raptor-pwned"). Feed it in and you get:

not a RAPTOR tree: expected a pickled raptor.tree_structures.Tree at the top level,
found a posix.system object

— and the test asserts the file was never created. Ten hardening cases (lengths claiming 2^62 bytes, truncated input, unknown opcodes, unfilled memo slots, protocol 0/1 text pickles) each fail in under half a millisecond with a message naming the opcode and byte offset, rather than allocating or looping.

Protocols 2–5 are supported, which is every protocol pickle.dump has defaulted to for years. Protocol 0 and 1 are text-based and rejected by name.

One honest caveat: the reader cannot execute anything, but that is not a licence to trust a file's contents. A hostile pickle can still describe a tree designed to mislead you.

Documentation

The last two are generated from one source, scripts/context.py, so they cannot drift; a test checks that every heading in the tree still appears in the prose. The handoff document being a tree in this project's own format also makes it a working example of the format — 93 nodes, four levels, with a summary at every level.

Contributing

Missing a format? An adapter is one file that turns a source into TreeNode objects and picks the roots. Everything downstream — validation, statistics, rendering — depends only on the format.

One gotcha worth knowing: roots are the nodes at the highest level, not "every node without a parent". On real data the latter returns the actual roots plus every orphan, which silences the orphan warning and drops lone leaves into the centre of the layout.

Licence

MIT