graphify

Builds a compact symbol graph of a codebase — declarations plus the relationships between them — so an AI tool can understand a project's structure at a fraction of the tokens of the raw source.

Why

Feeding whole files to an AI is expensive. A skeleton view keeps the module layout, imports, and every declaration's signature while dropping function bodies — the part that dominates token count but rarely matters for navigation.

// demo.v
module demo
  import os
struct User
const max_users
pub fn (u User) greeting() string { ... }
fn greet(name string) string { ... }
fn main() { ... }

Measured savings

Benchmarked on real external V codebases (vlib/v/ast, vlib/v/parser, c2v) with cmd/bench — see BENCH.md:

Artifact ceiling: ~10–20× fewer tokens for navigation/mapping (full source vs skeleton, apples-to-apples) — 89–95% reduction. This is a theoretical maximum, not what a session gets.
Live end-to-end (real claude -p A/B on a 2,885-file / 161-module corpus, both arms --safe-mode so neither inherits the user's graphify hooks):
- structural questions ("where is X, what calls it, what's in this module"), n=3, opus: ~1.3× fewer unique-input tokens.
- purpose/rationale questions ("what is X for, why does it exist"), n=3, sonnet, warm-cache rounds: ~1.33× fewer unique-input tokens, consistently — once query actually surfaces the doc it captures (see below), the model goes straight to one batched explain call per symbol instead of a full-body read.
- implementation walkthroughs ("explain step by step what this function does internally"): no gain — these require reading the actual logic, and the graph is an extra hop before that read, not a substitute for it.

That's the honest headline — ~1.3× on structure, ~1.3× on rationale (once wired correctly), ~1× on "explain this code". Turn count and total tokens looked better still but varied more run to run, so unique-input is the number to quote.

Two findings are worth knowing before optimizing further:

Call resolution went 53.7% → 82.9% and live savings did not move — for these tasks the bottleneck was never resolution accuracy.
The rationale task initially lost (0.77× avg, 0.44×–1.06× round to round) despite being built to favor docs. Root cause: query()'s rendered output omitted the doc field entirely — only explain showed it — while the wired system prompt recommended query first. The model would query, get no doc text back, and fall back to reading a whole function body. Adding a one-line doc preview to query() and steering the prompt toward explain for named-symbol lookups turned that into the consistent ~1.33× win above. A benchmark claiming "docs help" is only as honest as the wiring that actually exercises the docs.

For the gold-standard test — real Claude Code sessions, same task wired vs. not, comparing actual API tokens — see bench/live/PROTOCOL.md and bench/live/count_tokens.ps1.

Design

V only, by design: the extractor reads symbols and edges through V's own compiler frontend, which gives full fidelity with no separate grammar to maintain and no gaps from a minimal binding. An earlier draft sketched a second, tree-sitter-backed path for other languages (SourceFile.lang, a language filter on Options, a backend_ts.v stub); it was never implemented beyond that stub and has been removed rather than kept as unused scaffolding for a project that doesn't exist yet — see tree-sitter's own line in Status.

Pipeline: walk files -> extract_v_file(file) -> []Symbol + []Edge -> Graph -> emit.

Model

Symbol{ id, name, kind, signature, file, line, end_line, is_pub, parent, doc } — end_line is what lets get_body read one declaration instead of a whole file; doc is the // block directly above it
Edge{ from, to, kind, provenance } — kinds: defines, calls, imports, implements, embeds, references; provenance (extracted/inferred) is set on resolved calls, embeds, and references edges, and undeclared on an unresolved call that has no declaration to resolve to, or on a C. or JS. type reference that nothing declares — see the edge provenance item in Status
implements is a declared vocabulary slot, not a planned feature. V's interfaces are satisfied structurally — there is no impl X for Y syntax to read off the AST, so detecting it means matching a candidate's resolved method/field set (including through embeds) against every visible interface's, which needs a whole-program, fully-resolved type table exactly like v/ast/table.does_type_implement_interface builds — the opposite of graphify's per-file, parallel-worker, cacheable extraction. Investigated concretely, not just deferred by assumption: real yield data across 3 real corpora (V's own compiler, this project, and a real veb-framework app) found the obvious pitch — a project's own type implementing a project's own interface — in zero of 288 measured pairs, including a corpus that declares 6 of its own interfaces specifically to test this. The one real signal (app code satisfying a framework's interface) scored 2 meaningful pairs in the one corpus built to have it; the other 286 pairs were stdlib-satisfying-stdlib facts (io.ReaderWriter, IError) — the same static fact in every V program, not project-specific insight. Building this would mean a standing compiler-patch dependency (forking or upstreaming a change to v/ast/table.v) for a feature that, on the best evidence gathered, finds a handful of edges per framework-consumer project and nothing in most others.

Emitters

emit_skeleton() — body-less code view (the token-saver)
emit_json() — full graph for tooling

Usage

Mirrors the Python Graphify command surface: extract once, then traverse instead of re-reading files.

graphify extract  . --out /path/to/graph_data  # build graph -> a central dir
graphify overview                              # compact summary (counts + key symbols)
graphify query    "auth flow" --budget 2000    # token-bounded traversal
graphify path     build_graph emit_skeleton    # shortest path between symbols
graphify path     http.get net.dial_tcp --routes 20   # list more chains of calls than the 5 shown
graphify explain  build_graph                  # a symbol + its relationships
graphify body     build_graph                  # just that declaration's source
graphify skeleton .                            # body-less skeleton of a path
graphify merge-graphs a/graph.json b/graph.json --out merged.json   # combine two graphs
graphify communities --resolution 1.5          # split the graph into subsystems
graphify export graphml --out graph.graphml    # for Gephi, yEd, Cytoscape, NetworkX
graphify export cypher  --out graph.cypher     # for Neo4j: cypher-shell < graph.cypher
graphify export svg     --out graph.svg        # static, community-clustered node-link diagram
graphify export html    --out graph.html       # the same, interactive: hover/lock/trace/zoom, + to drill into large communities

The standard library and installed modules. A project outside the V tree has no vlib in it, so extract also reads the modules it imports from vlib (the V checkout of the v on PATH, or VROOT) and from ~/.vmodules (or VMODULES), and their imports in turn, so its calls into them resolve: s.contains(x) goes to vlib.builtin.string.contains rather than to the project's only contains, and os.join_path to its declaration. The library declarations the project reaches are kept in graph.json's library section, apart from the project's symbols: explain lists them, marked [library], and body reads them from VROOT, but they take no part in query, path, communities, the exports, diff or the most-connected list. The report counts an edge into the library as library. --no-library turns this off, and so does VROOT=; extracting the V tree itself reads nothing extra. On ~/.vmodules/gui unresolved calls go from 2,201 to 6 (FUTURE_WORK.md §10).

SVG/HTML. Nodes are laid out by community (see Communities above), not by a force-directed simulation: communities are arranged around an outer circle, each community's own members around a smaller circle centered on its spot. Deterministic trigonometry instead of an iterative physics simulation that would need its own convergence/quality verification the way communities.v's Louvain implementation did — genuine physical realism isn't the goal, showing which symbols cluster into which subsystem (and roughly how large each one is) is. Node size is degree, color is community, hovering a node in the HTML version highlights it and its direct neighbors and shows its name/kind/id — plain DOM/SVG event handling, no framework, no CDN dependency, matching the rest of graphify's fully local design. Caps at 300 symbols (the highest-degree members of each community, kept proportional to that community's own size so a few giant communities can't crowd out every small one) since a large real codebase's full node count is too much to usefully render or even open; a rendering that got capped says so in an HTML comment / on-page caption rather than silently passing as complete. No amount of client-side tuning changes that for a genuinely huge repo (tens of thousands of symbols) — putting every node on one screen at once stops being legible long before it stops being possible to draw. For that scale, export graphml/export cypher are already uncapped and meant to be opened in a tool actually built for graphs that size (Gephi, Neo4j Bloom) rather than a hand-rolled SVG.

The HTML version also has scroll-to-zoom (centered on the cursor) and drag-to-pan on the SVG viewBox, added after direct testing found the first version impractical to actually use: a real WebDriver-synthesized mouse move (not a JS-dispatched event — the browser preview tool available during development renders local files as static snapshots with no JS execution at all, so a synthetic dispatchEvent had been the only check, and it passed without exercising the real problem) landed dead-center on a node and measured its rendered size at ~4×4 CSS pixels — correct in principle, unusable with an actual mouse. Fixed two ways, both verified the same way afterward: each node's hover target (.hit in the SVG, invisible, layered under the visible dot) is now sized independently of the dot's degree-based visual size, roughly 3× larger; and the added zoom lets a user close whatever gap remains. Confirmed with real synthesized interactions, not just reading the JS: a pointer move to the enlarged target still highlights correctly, a dispatched wheel event visibly shrinks the viewBox width by the expected factor, and a real mousedown-move-up drag shifts the viewBox origin.

Semantic zoom and cluster context. The default view shows only one bold label per community — its name, member count, and where in the source tree it actually lives (e.g. main (22) — cmd/cli +2 more dirs) — with individual symbol labels hidden, so the first thing you see is a high-level map, not a wall of overlapping per-symbol text. Zooming in past a threshold fades the per-symbol labels in; the cluster label stays anchored throughout for context. The directory info exists because a community's own label (its most internally-connected member's name — see label_community) doesn't say what part of the codebase it corresponds to, and graphify doesn't otherwise show repo directory structure anywhere; community_location reports the single directory most members share when there's a strict majority, or a plain count of distinct directories when there isn't one — guessing a "best" directory for a genuinely scattered community would misrepresent it, not describe it. Verified live in a real browser: the default view shows communities with node labels at opacity:0; scrolling in on a specific cluster flips svg.zoomed-in and reveals that cluster's full member names while the rest of the graph stays uncluttered off to the side.

Click to zoom, lock, and trace. Clicking a legend entry, or a cluster's own label on the canvas, zooms the viewBox to fit that community — no need to scroll-zoom by hand to find where a cluster from the legend actually sits in the layout. Clicking a node locks its hover highlight so it survives the mouse moving away: pan or scroll around a node's neighbors at leisure, or click one of those now-visible neighbors to re-lock onto it and trace a path across communities one click at a time (click the same node again, or empty canvas, to drop the lock). The locked node, its neighbors, and the edges connecting them get a distinct stroke — black for the node itself, orange for its neighbors and the edges reaching them — instead of relying on everything else merely getting dimmer to imply connectivity, which was easy to lose against a cluster's own now-dimmed edges.

Verified with real WebDriver clicks, not dispatchEvent, which caught two real bugs neither a code read nor a synthetic check would have surfaced. classList.toggle(cls, x) treats an explicit undefined x as "no force argument given" — falling back to flip-on-current-presence — rather than "force false"; since keep[nid] && nid !== id evaluates to undefined (not false) whenever keep[nid] itself is unset, this silently marked nearly every node in the graph as a "neighbor" on top of correctly being "dim." And the pan-starter's mousedown handler was calling unlock() on every mousedown, including a plain click with no drag, nulling out the lock before the click handler's own "am I re-clicking my own lock?" check could ever see it — breaking click-the-same-node-to-unlock outright. Both fixed (a !! coercion before the affected toggle() calls; deferring the pan-triggered unlock until real pointer movement is detected) and re-confirmed the same way: real clicks on legend entries and cluster labels shrinking the viewBox to the expected community, a locked node's neighbor/dim counts summing exactly to the total node count, re-clicking a locked node cleanly dropping every highlight, and clicking through to a neighbor correctly demoting the previous selection while promoting the new one.

That "defer unlock until real pointer movement" fix later turned out to overcorrect: it dropped a lock on any drag, including one starting from a locked node — which defeats the reason locking exists, panning or scroll-zooming out to see where a highlighted edge actually leads. Fixed to only clear a transient, never-locked hover highlight on pan; a deliberate lock now survives it. That exposed a second issue directly underneath: a real synthesized ~90px drag still made the browser fire a trailing click event at mouseup, which was immediately re-triggering unlock right back through the other click handler the moment the pan fix stopped dropping it directly — invisible without tracing the actual mousedown/mousemove/mouseup/click sequence a real drag produces, not just reading the code. Fixed by having the node and background click handlers ignore a click that's the tail end of a just-finished drag. Confirmed with a real WebDriver-synthesized drag (not a single click): a locked node's highlight classes and dim count come out byte-identical before and after panning, while the viewBox itself genuinely moved.

Drill down into large communities. A large, internally-lumpy community gets a small "+" badge next to its legend entry and in-canvas label — computed by communities_within, a scoped re-run of the same Louvain optimization on just that community's own members and edges, gated on it actually finding a real split (>= 2 sub-communities), not just on size alone. Clicking the badge reveals a precomputed nested sub-layout, using the same deterministic ring layout and node/edge/label rendering as the top level, complete with its own directory-location context per sub-cluster; an explicit "back to overview" button (not a re-click toggle or an implicit zoom-out threshold — this project already learned that lesson once, see above) reverses it. Capped at the 10 largest qualifying candidates, bounding both the extra clustering cost (each scoped run has its own restart loop) and the payload growth, with the truncation disclosed on-page ("N of M large communities include a detail view") the same way the 300-node cap already is — never silent.

The size threshold (30 members) is empirically grounded, not a guess: tuned against the classic Fortunato–Barthelemy "ring of cliques" resolution-limit case, the textbook example of a community that plain modularity optimization provably cannot resolve further at the top level yet still contains real, recoverable sub-structure once analyzed in isolation — a plain clique-of-cliques (few cliques, one clean bridge) turned out to always get cleanly separated by communities() at the top level too, confirmed directly after several other hand-built test graphs kept failing this exact way, which would leave nothing for drill-down to ever find.

Two real bugs surfaced only by testing against an actual ~47k-symbol codebase, not the smaller synthetic test graphs the feature was built against: the drill badge's fixed small offset from the cluster label placed it inside a large community's own member ring (whose radius grows with sqrt(member count)), so a real click landed on a member node instead — fixed by measuring each community's actual rendered spread and placing the badge outside it. And a drill-view's hidden .dot circles stayed independently clickable even at opacity: 0, since only the larger .hit/.cluster-hit targets had an explicit pointer-events: none override — opacity never implies pointer-events: none on its own — fixed by covering .dot too, in both the hidden-drill-view and hidden-flat-content directions.

Export. Both formats emit one node per unique symbol id via Index.by_id rather than one per raw Symbol, and only resolved edges (Index.edges) — the same reasoning as query/explain: an id like main (every standalone V program's entry module) or graphify (this project's own module, declared identically in every one of its own files) is shared by several distinct real declarations, and an unresolved edge has no real node to point at. This isn't just consistency for its own sake — the Cypher export declares a uniqueness constraint on id for fast edge lookups, and a naive one-node-per-raw-symbol version was confirmed to violate that constraint against this project's own export (its own files collide on graphify), failing outright rather than degrading gracefully. GraphML escapes &<>"'; Cypher property strings escape \ and ' only — <, >, &, " don't need it inside a single-quoted Cypher string, and escaping them anyway would corrupt the data (this was cross-checked directly: a signature containing all of <>&" round-trips unescaped in the Cypher output, escaped in the GraphML one).

Communities. Splits the graph into densely-interconnected subsystems by modularity optimization — the same idea Python Graphify ships as "Communities: the graph split into subsystems (Leiden), with LLM-free labels." What this implements, precisely, since "Leiden" names a specific algorithm and it's worth being exact about the difference: Louvain-style local-moving + multi-level aggregation (the same core as the original Louvain algorithm), followed by a connectivity-guaranteeing pass that splits any resulting community whose induced subgraph turns out disconnected into its connected components. That delivers the same practically-important guarantee the Leiden paper's randomized refinement phase exists to prove — every returned community is one connected piece — via a much simpler, much easier-to-verify mechanism (connected-components is a solved primitive; a randomized multi-way refinement merge is not something to hand-roll and trust without a reference implementation to check against).

Verified against Zachary's Karate Club, the standard 34-node benchmark for this exact algorithm: correctly separates the graph's two well-documented rival factions every run, and (since local-moving is randomized and any single run can settle into a meaningfully weaker local optimum purely by chance) communities() retries --restarts times and keeps the highest-modularity result — more restarts is slower but more reliable; the default balances the two. defines/imports/implements edges don't count toward community weight, only calls/references/embeds — containment ("this module defines this function") isn't "these two things interact", and including it pulled unrelated members of the same module toward each other instead of toward whatever they actually collaborate with.

Fixed: Index.by_id no longer collapses distinct declarations that share an id. It used to — the same case resolve_edges' unaddressable check already named for call resolution (every standalone main program's entry point is main.main; every _test.v file's helpers can collide the same way) silently dropped whichever declaration wasn't indexed last, everywhere Index.by_id is used: query/explain/get_node, communities, GraphML/Cypher export. Measured on the V compiler repo before the fix: 21.03% of all 107,134 symbols were silently discarded this way, 17.11% of them genuinely distinct declarations, not harmless duplicates. extract now runs disambiguate_ids before edge resolution: a declaration whose id collides across separate build units (every standalone main program, or an id repeated across ≥2 distinct _test.v files — same classification unaddressable already used, just applied earlier) is renamed to id@file, file-qualified and so unique for any two declarations V itself would accept as distinct; a same-declaration repeat inside one ordinary module (a per-platform variant like os.setenv in both environment.c.v and environment.js.v) is untouched, since V would reject a genuine redeclaration there; Index shows such an id's C-backend declaration (.v/.c.v) ahead of a .wasm.v/.native.v one, and a .js.v one last (shown_before in graph_ops.v) — 238 ids on the V compiler's tree used to show the JS or WASM copy. Post-fix on the same repo: 13.54% of symbols still collapse, entirely the mod_/import_/constant/field kinds this pass deliberately doesn't touch (matching resolve_edges' own scope) plus legitimate platform variants — of the 7,646 rows that were genuine cross-build-unit collisions, 7,638 (99.9%) were fixed here; the remaining 8 were a separate, root-caused bug that a file-qualified suffix can't help with — a fn C.foo/fn JS.foo extern declaration colliding with a same-named V wrapper in the same file, since fn_id (backend_v.v) doesn't preserve the language prefix in short_name — since fixed by skipping body-less non-V FnDecls as symbols entirely (call resolution to an extern callee was already non-functional either way, so nothing that worked is lost); a fresh full-repo extraction now shows 0 duplicate ids across all six kinds this pass targets. Before excluding containment edges, the old collapse also produced an artificial "main" supermassive community spanning every unrelated standalone program in a large corpus; excluding defines edges from community weight remains independently correct (containment isn't interaction) even now that the underlying collision itself is fixed.

Regressed and fixed again (October 2026). When module ids became directory paths (5170207, so that two machines produce the same ids), the checks for a standalone program kept comparing a symbol's parent with main. A program in a subdirectory now has a parent like cmd.tools, so from then on the 62 programs in vlang's cmd/tools shared one cmd.tools.main and calls between them crossed programs; 3,081 declarations fell into 1,169 ids. The same change broke the visibility rule in call and type resolution, which compared directory ids such as vlib.os with import paths such as os and with builtin. The module symbol's signature now records what the file declares (module main), which main_unit_files reads, and imports match a module id by its trailing segments (import v.ast reaches vlib.v.ast; where that fits several modules, nothing is resolved). On vlang 1b4ecb9c05: resolved calls 130,513 → 163,984 and resolved type references 41,296 → 65,702, every remaining multi-declaration id a platform variant inside an ordinary module. Two older bugs then surfaced: the worker protocol never carried Edge.file, and the call walker dropped it after any typed local (x := Foo{}), so a renamed declaration's calls came out from id@, an id that does not exist. With both fixed, the 3,095 renamed functions keep their calls (2,841 have outgoing edges; the rest call nothing) and no edge starts at a missing id (11,409 before).

Fields and consts beside a same-named method or function. V lets a method share its name with a field of its receiver type (Server.username in vlib/crypto/scram is both) and a const share its name with a function; each pair came out as one id, so 429 calls edges on vlang pointed as much at a field as at the method. separate_member_ids gives such a field or const the id <parent>::field::<name> or <parent>::const::<name>, the form import ids already use, and leaves the plain id to the method or function that edges point at. A C struct has an id of its own, <module>.C.<name>, as its methods do, so it no longer shares one with a V type of its name (type Size = C.Size, the interface IError, the function os.stat; 9 ids on vlang, October 2026). Left as they are: a module id that equals a member of the parent module (vlib.rand.seed, both a submodule and a function; 5 ids), a JS binding type sharing an id with a V type of the same name (vlib.builtin.js.Error and vlib.builtin.js.Promise), and duplicates written twice in the source itself (the same C. structs declared twice in vlib/sokol/sapp/sapp_linux.c.v; import samename next to import samename as sn).

Merging graphs. Every id is namespaced by its source graph's label (its root directory name by default, or --labels a,b,...), unconditionally and regardless of merge order, because two unrelated projects sharing a module name is the common case, not an edge case — main is the implicit module of every standalone V program, so any two merged programs collide on main.main unless kept apart. query/explain/path/shortest_path/ overview work normally against the merged result, and so does get_body: the merged graph carries a roots map from each source's label chain (the same label:: prefix its symbol ids carry) back to that source's own original root, so get_body picks the right root per symbol instead of needing one root for the whole graph. --source-dir still overrides the single root field when set, which only matters for a non-merged graph or for forcing every symbol through one relocated checkout. Content that's genuinely duplicated across inputs (the same file extracted into two of them) is not deduplicated — it appears twice, once per label.

Queries read ./graphify-out/graph.json by default. Override with --graph <file>.

Central store (recommended for multiple projects). Set GRAPHIFY_STORE once; then extract auto-files each project under <store>/<project-name>/, and queries resolve the graph for whatever project directory you're in — no path juggling:

$env:GRAPHIFY_STORE = 'S:\graph_data'
cd my-project ; graphify extract .      # -> S:\graph_data\my-project\graph.json
graphify overview                        # resolves S:\graph_data\my-project\graph.json

Resolution order: --graph > GRAPHIFY_GRAPH > GRAPHIFY_STORE/ > ./graphify-out.

extract writes a Graphify-style bundle to graphify-out/:

graph.json — persistent, queryable graph (read by query/path/explain)
GRAPH_REPORT.md — counts, most-connected symbols, suggested queries
manifest.json — metadata + counts
.gf_cache.ndjson — incremental cache: each file's content hash plus its extracted symbols/edges. A file whose hash matches the cache is reused as-is on the next extract instead of being reparsed — only new/changed files hit the parser. The whole cache is also tied to a hash of the graphify binary that wrote it, so a rebuilt binary with different extraction logic can never silently serve stale results just because the source files themselves didn't change. Safe to delete to force a full reparse.

Library:

import graphify

g := graphify.build_graph(graphify.Options{ root: 'path/to/project' })
// build_graph (unlike build_graph_resilient) doesn't track a binary hash or
// per-file failures, so its ExtractReport is empty.
graphify.write_bundle(g, 'graphify-out', graphify.ExtractReport{})!
println(g.query('auth flow', 2000, false))

MCP server (for Claude Code and Codex)

cmd/mcp is an MCP server over stdio, on V's mcp module, that loads a persisted graph.json and exposes graph traversal as tools, so the model queries the graph instead of reading source files. It reloads the graph when an extract replaces graph.json, so re-extracting needs no client restart. The same server works with both Claude Code and Codex:

Tool	Purpose
`overview`	body-less skeleton map of the whole codebase
`query_graph(text, budget?, dfs?)`	token-bounded traversal from the symbols that match every word of `text` (in name, signature, file or doc), best first
`get_node(node)`	a symbol + its relationships (defines, references, embeds, calls), each with file:line; a call also with the lines it is made on; for a declaration only some builds compile, their condition (`[$if use_openssl ?]`) and the other builds' declarations of it; for a call made only inside a `$if`, its condition (`at line 39 [$if linux]`)
`get_body(node)`	the source of ONE declaration by name (instead of reading its file); notes when that file has changed since the graph was built
`get_neighbors(node)`	names of all directly linked symbols
`shortest_path(a, b, routes?)`	how `a` reaches `b`: how many chains of calls lead from `a` to `b` (at most 10 calls longer than the shortest, and none through builds that contradict each other, `use_openssl ?` and `!use_openssl ?`), and the 5 shortest (`routes` for up to 50), those the default build has first, each call with the line it is made on and its `[$if …]` build, each route with the build it needs (or those from `b` to `a`); with none either way, the shortest link through any relation

A node is an id (net.unix.StreamListener.accept), a dotted tail of one (StreamListener.accept, unix.StreamListener.accept), a file:line inside a declaration (vlib/net/unix/stream.c.v:290), or a name. A name with several declarations is each of them: get_node wait_for_read shows all 8, each with its own callers, and get_body reads up to 4. A name with more than 8, such as str, is a list of them, the most called first, to name one from.

query_graph seeds from the symbols that match every word of its text, in their name, signature, file or doc comment, leaving out question words (how, the, does); with none that match them all, from those that match the most. They come best first: a word that is the whole name, then one in it, in the signature, then in the file or doc; a test's declaration counts half. At most 50 seeds.

A call is listed with the lines it is made on, in the caller's file: called by : read_ptr (vlib/net/tcp.c.v:183) at lines 198, 224. graph.json keeps them on each calls edge as lines; a graph extracted before has none, and lists its calls as before until it is extracted again.

Build and register it with the client you use. The binary name gets an .exe suffix on Windows only; the rest of this doc omits it.

Build with current V (the V3 compiler); run the tests with v test .. Before a push, v run bin/test-crlf.vsh runs them again on a checkout of HEAD with CRLF line ends, as Windows CI checks it out, so that a test that would fail only there (one comparing a multi-line string literal, say) fails here first. Extracting the V compiler repo peaks at about 1.3 GB. On macOS 27, V itself has to be built with -cc cc until vlang/v#29744 is fixed (a V binary linked by its bundled TCC can start with garbage in its globals); graphify's own builds need nothing extra.

v -prod -o bin/graphify         cmd/cli     # extract, query, etc.
v -prod -o bin/graphify-hook    build cmd/hooks/graphify_hook.vsh   # Claude Code hook, see below
v -prod -o bin/graphify-mcp     cmd/mcp
bin/graphify extract .                 # produce graphify-out/graph.json first

Any checkout builds its own sources, including a Claude Code worktree under .claude/worktrees/: graphify/alias.v points import graphify at the checkout holding it. From the main checkout, v test . also runs every worktree's copy of the tests (FUTURE_WORK.md §9).

The hook needs the build subcommand because its source is a .vsh script. Without it, V treats the file as a script to compile and run. Each build then executes the hook as a side effect, and the build goes through V's compile-and-run cache, which can leave an existing bin/graphify-hook in place instead of rebuilding it — while still exiting 0.

Claude Code

.mcp.json (already in this repo, gitignored — copy .mcp.json.example if you don't have one) uses Claude Code's ${CLAUDE_PROJECT_DIR} path expansion, so it works unedited on any machine; the one thing to check per OS is the .exe suffix on command:

{
  "mcpServers": {
    "graphify": {
      "command": "${CLAUDE_PROJECT_DIR}/bin/graphify-mcp.exe",
      "args": ["${CLAUDE_PROJECT_DIR}/graphify-out/graph.json"]
    }
  }
}

Or register globally:

claude mcp add graphify -- /path/to/bin/graphify-mcp /path/to/graph_data/vlang/graph.json

Codex

Codex reads MCP registrations from ~/.codex/config.toml (or a trusted project-scoped .codex/config.toml). Register the same server against the graph extracted from the V-language repository:

[mcp_servers.graphify]
command = "/path/to/graphify/bin/graphify-mcp"
args = ["/path/to/graph_data/vlang/graph.json"]
enabled = true

The equivalent CLI command is:

codex mcp add graphify -- /path/to/graphify/bin/graphify-mcp /path/to/graph_data/vlang/graph.json

Restart the client after registering or switching the graph so it reloads the MCP server configuration (a re-extract of the same graph doesn't need one).

Your own projects, layered on vlang. Add --projects <store>, the directory extract --store writes project graphs into:

claude mcp add graphify -- /path/to/bin/graphify-mcp /path/to/graph_data/vlang/graph.json --projects /path/to/graph_data

A session whose directory is inside a project in the store, or inside a worktree of one, then gets that project's graph with vlang's vlib under it: one shortest_path, get_neighbors or get_node goes from the project's code into gg, sokol or builtin, because the project's calls into vlib already name vlang's ids. query_graph seeds from vlib's matches as from the project's, the project's first where they match as well; the overview is the project's, and a vlib declaration is marked [library]. Anywhere else the server serves the vlang graph alone, as before. The note at the top of a result also says when the project read vlib from another checkout or commit than the vlang graph is of. See FUTURE_WORK.md §11.

A session in a git worktree of a project, or of vlang, inside the checkout as Claude Code makes one (.claude/worktrees/) or beside it, gets the graph of the worktree's own branch. The session's directory is the client's MCP root (roots/list), which the server asks for: the desktop app starts a server in the project's own checkout, not the session's worktree. The server extracts the worktree in the background, with the bin/graphify beside it, into a store of its own under ~/.cache/graphify/worktrees (or GRAPHIFY_WORKTREE_STORES), seeded with the checkout's extract cache so that only the files the branch changed are parsed: about half a second for a project, six seconds for vlang. Until it is there the checkout's graph is served, with a note saying so. When a V file of the worktree changes, committed or not, the next tool call starts another extract, and the graph is replaced when it is done. A store whose worktree is gone is removed when a server starts.

One daemon answers for every session. Each session's server is a small relay (about 12 MB) that passes its tool calls over a Unix socket in ~/.cache/graphify (or GRAPHIFY_DAEMON_DIR) to graphify-mcp --daemon, which the first server starts. The daemon reads vlang's graph and its index once, and keeps a layered graph for each session's directory, whose index falls through to the base's, so a session costs a few MB for its project rather than a whole server's 1.1 GB: four sessions (gui, vebidor, graphify, vxui) took 1.18 GB in the daemon, against 2.26 GB when each layer copied vlib's symbols. A daemon exits 15 minutes (GRAPHIFY_DAEMON_IDLE seconds) after its last session goes, or once none is connected when bin/graphify-mcp has been rebuilt; a rebuilt server starts a daemon of its own. Its log is beside its socket. A daemon that exits on its own removes its socket and leaves its log (and on Windows its copy of the binary); a daemon that is running removes those when it next looks whether it is done (about every minute while no server connects), once the log is a minute old, and a daemon starting removes a killed daemon's files at once. On Windows (10 1803 and later, which have Unix sockets) the daemon runs from a copy of graphify-mcp.exe beside its socket, since a running .exe can't be rebuilt. It is started detached, with no console and none of the server's handles, so it outlives the session that started it as it does elsewhere. GRAPHIFY_MCP_DAEMON=0 has each server read the graphs itself, as one does when the daemon can't be reached.

Stale-graph notes. Both the CLI (on stderr) and the MCP server (at the top of a tool result) say when the graph may be out of date, from the manifest.json beside it: when the source checkout has moved past the commit the graph was extracted from (... is at 89371e2b13 (3 commits ahead)), or when the graphify that would extract it again isn't the build that did, or when the vlib or a module under ~/.vmodules that it read has moved on. A graph read with --source-dir / GRAPHIFY_SOURCE_DIR, shared from another machine, is compared by commit only. Uncommitted edits aren't reported. Smoke-test the protocol independently of either client with:

cat cmd/mcp/test_session.jsonl | bin/graphify-mcp /path/to/graph_data/vlang/graph.json

Operational scripts

Beyond the graphify CLI itself, bin/ and bench/ hold V shell scripts (.vsh, run via v run — no separate scripting language or interpreter to install, since every machine running this already has V) for running this against a large external repo (vlang) day to day. The exceptions are the Claude Code hook (below), which is prebuilt for latency reasons rather than run via v run, and the scheduled refresh on Windows, which also runs as a prebuilt exe (see Scheduling).

One-time setup: copy graphify.config.json.example to graphify.config.json (repo root) and edit the paths for your machine:

{ "vlang_repo": "/path/to/repo/vlang", "store": "/path/to/graph_data" }

Add "projects": ["/path/to/a/project", ...] to have update-vlang-graph.vsh extract your own projects into the store after vlang, for the MCP server's --projects. A project is re-extracted when its commit moved, graphify was rebuilt, or vlang changed; it is never pulled.

graphify.config.json is gitignored — each machine keeps its own copy, and update-vlang-graph.vsh, switch-vlang-graph.vsh, and extract_bench.vsh (its default -Source) all read from it. If the file is missing, each script errors with a pointer back to the .example template instead of silently using the wrong paths.

`bin/update-vlang-graph.vsh` — scheduled graph refresh

Pulls graphify and the target repo, rebuilds graphify if it is out of date, and re-extracts each graph that is out of date. Wired into a scheduler — Windows Task Scheduler, macOS launchd, or Linux cron, see Scheduling below; can also be run by hand.

v run bin/update-vlang-graph.vsh                  # pull both; extract what is out of date
v run bin/update-vlang-graph.vsh -NoPull          # pull neither (after your own `v up`)
v run bin/update-vlang-graph.vsh -Force           # re-extract every graph, out of date or not
v run bin/update-vlang-graph.vsh -Commit <sha>    # move up to that commit, not the newest
v run bin/update-vlang-graph.vsh -NoBuild         # never rebuild graphify
v run bin/update-vlang-graph.vsh -PrintStamp      # print the build stamp and stop

graphify's binaries depend on graphify's own code and on the V that builds them: the compiler, the v on PATH, and the vlib and thirdparty (the garbage collector) it compiles in. The script records what each build saw in bin/.build-stamp (graphify's commit and uncommitted changes, v version, and the git trees of vlib and thirdparty with their uncommitted changes) and, after pulling, rebuilds bin/graphify and any graphify-mcp and graphify-hook beside it whenever that no longer matches. Each binary is built under a temporary name and swapped in, so an MCP server that is running it doesn't block the build on Windows. So every v up rebuilds them, about 36 s: a new compiler can change how they run even when the graph they extract is the same (vlang/v#30996, a fix in the C backend alone, stopped graphify-mcp losing live strings to the garbage collector). If v isn't a git checkout, the stamp names its vlib and thirdparty directories instead. -PrintStamp prints the stamp and stops.

A graph, vlang's or a project's, is out of date when it has none yet, or its manifest.json says it was extracted from another commit of its repo, by another build of bin/graphify, or, for a project, from vlang's vlib at another commit, or from a module under ~/.vmodules at another commit of its clone (v update, or a pull in it: extracting gui (vglyph moved)...). A pull or a rebuild therefore shows up on its own, and a run after your own v up with -NoPull extracts what moved and skips the rest, each with its reason in the log (extracting graph (its commit moved)...). Uncommitted edits, and a module there that isn't a git clone, aren't seen; -Force re-extracts every graph.

The extracts read vlib and ~/.vmodules from the V tree in VROOT, which the script sets when it is empty. It takes the tree of the v on PATH, else of the v running the script, since a scheduled task's PATH may have no v. Without a V tree an extract has no libraries: calls into vlib and ~/.vmodules stay unresolved. The log names the tree on each run (libraries: vlib from …, VMODULES …). A graph extracted without its libraries is out of date once a tree is found (extracting graph (it was extracted without its libraries)...).

graphify's own checkout is fast-forwarded first, so a change merged to master reaches every machine on its next scheduled run. A checkout with uncommitted changes, or not on a branch, is left as it is, and a failed pull of it only logs a warning. The prebuilt bin/update-vlang-graph.exe the Windows task runs is rebuilt along with the other binaries, and the .<name>.v3cc.* directories V's compiler leaves in bin/ are removed once they're an hour old.

-Commit lets two machines extract exactly the same source: it fetches and fast-forwards the repo to that commit, and refuses to move it back or off its branch. Logs to <store>/update.log.

`bin/switch-vlang-graph.vsh` — branch-aware graph switching

Extracts (or reuses) a graph for a specific branch and repoints the MCP server's ~/.claude.json config at it. master/main keep the graph at <store>/vlang; other branches get their own <store>/vlang-<branch>. The ~/.claude.json edit is a targeted text splice of just that one field, not a full rewrite — see the comment on patch_mcp_args in the script for why (a full parse+re-encode round-trip was tried first and found to silently corrupt unrelated floating-point fields elsewhere in the file).

v run bin/switch-vlang-graph.vsh                             # graph for the current branch
v run bin/switch-vlang-graph.vsh feature-x                   # graph for a specific branch
v run bin/switch-vlang-graph.vsh feature-x -Checkout          # also `git checkout` that branch first
v run bin/switch-vlang-graph.vsh -Force                      # re-extract even if a graph already exists
v run bin/switch-vlang-graph.vsh <worktree-path>              # graph for an existing worktree
v run bin/switch-vlang-graph.vsh <worktree-path> -Force       # same, forcing a re-extract

A positional arg that names an existing directory is treated as a worktree path, not a branch name: it's extracted directly, the stored graph is labeled after whatever branch that worktree is already checked out to, and -Checkout is ignored (a worktree is already on its own branch). This is the normal case for a one-worktree-per-feature-branch convention, where the shared main checkout is never git checkout-ed away from its own branch — pass the worktree's path directly rather than a branch name.

A brand-new graph (worktree or plain branch) isn't a full rescan either way: master's own .gf_cache.ndjson is copied in to prime the target's cache before extracting, so only files that actually differ from master's current tree get reparsed — measured on a real branch one commit ahead of master, ~60-90s full scan vs. ~8s primed. Best-effort and silent on a cache miss (no prior master extract yet just means a normal full scan, same as before this existed); skip it deliberately (rare — building a graph against some other, unrelated base) by deleting the target's .gf_cache.ndjson before rerunning with -Force.

Restart Claude Code after switching so the MCP server picks up the new graph.

`bench/session_stats.vsh` — token-free MCP usage stats

Scans Claude Code's session transcripts and reports graphify tool-call counts per session (main-agent vs. subagent split), at zero token/API cost.

v run bench/session_stats.vsh                  # last 14 days
v run bench/session_stats.vsh -Days 30         # look back further
v run bench/session_stats.vsh -IncludeBench    # include graphify's own bench sessions

`bench/extract_bench.vsh` — repeatable extraction benchmark

Times graphify extract end-to-end against a target repo, clearing the output directory first so every run starts cold.

v run bench/extract_bench.vsh                          # defaults: configured repo, temp out dir
v run bench/extract_bench.vsh -Runs 3                  # average over 3 runs
v run bench/extract_bench.vsh -Source /path/to/myproject -Out /tmp/gf-bench-myproject

Scheduling — Windows / macOS / Linux

All three schedule the same bin/update-vlang-graph.vsh; how often is up to you. With no new commits it exits right after the pull, and with new ones the incremental cache keeps a re-extract of the vlang repo to tens of seconds, so a frequent schedule is cheap (the author's Windows task repeats every 2 hours).

Windows: the task runs a prebuilt bin\update-vlang-graph.exe through a hidden pwsh, not v run. Build it first:
```
v -prod -o bin\update-vlang-graph.exe build bin\update-vlang-graph.vsh
```
Then create the task in the Task Scheduler GUI with:
- Trigger: time-based, repeating at the interval you want.
- Action: program pwsh.exe, arguments -NoProfile -WindowStyle Hidden -Command "& 'C:\path\to\graphify\bin\update-vlang-graph.exe'". (The author's task also sets Start in to the repo root, but nothing in the script depends on the working directory.)
- Settings: keep "do not start a new instance" as the rule when a run is still going, and set an execution time limit (the author's is 1 hour) so a run that gets stuck is ended instead of blocking every later one.
Three details are easy to get wrong:
- Use the build subcommand. Without it V treats a .vsh as compile-and-run, so building the exe would execute a real pull and extract on the spot (see the hook build note above for the stale-binary side of the same problem).
- The exe is a snapshot. It bakes in the checkout path (@VMODROOT), which is how it finds graphify.config.json and bin\graphify.exe. Each run rebuilds it when graphify has changed, so build it by hand only the first time and after moving the checkout.
- The pwsh wrapper is what hides the window. Task Scheduler's Hidden option only hides the task from its list; a console program that an interactive-logon task launches directly still opens a window. A child of pwsh -WindowStyle Hidden inherits the hidden console through the & call operator (Start-Process would open a new, visible one). -NoProfile keeps your PowerShell profile out of an unattended run.
macOS: copy bin/com.graphify.vlang-update.plist.example to ~/Library/LaunchAgents/com.graphify.vlang-update.plist, edit the /path/to/... placeholders, then launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.graphify.vlang-update.plist. Unlike Windows, the plist runs v run on the script directly, so there is no separate build step for the script itself. Chosen over cron: modern macOS restricts cron from accessing files outside a few whitelisted locations without manually granting it Full Disk Access, so a stock cron job for this fails silently; launchd needs no such grant.
Linux: a plain crontab line is enough for one daily command — crontab -e and add 0 3 * * * v run /path/to/graphify/bin/update-vlang-graph.vsh >> /path/to/graph_data/cron.log 2>&1.

On every platform the job rebuilds bin/graphify itself when graphify or V's vlib has changed (see above). The first extract after a rebuild is a full re-parse, because the incremental cache is tied to the binary that wrote it. The Windows task's own update-vlang-graph.exe is rebuilt with them.

Claude Code wiring

.claude/ makes Claude Code reach for the graph automatically (this repo dogfoods it on itself):

.claude/skills/graphify/SKILL.md — tells Claude to query the graph (MCP tools or CLI) for structural questions and drill into bodies by file:line.
.claude/commands/graphify.md — /graphify [path] rebuilds the graph and summarizes GRAPH_REPORT.md.
.claude/settings.json (gitignored — copy .claude/settings.json.example, same per-machine pattern as graphify.config.json/.mcp.json) — a SessionStart hook injects standing guidance, and a PreToolUse hook on Read|Grep|Glob reminds Claude to consult the graph before reading or scanning V files. Both call bin/graphify-hook — the compiled cmd/hooks/graphify_hook.vsh above — directly. It's prebuilt rather than run via v run because this hook fires on every Read/Grep/Glob/SessionStart, and v run recompiling from source each time costs several seconds per call — the prebuilt binary responds in well under 100ms. The command names the binary without an extension: V always appends .exe on Windows, and the shell Claude Code runs hooks through there (Git Bash) finds graphify-hook.exe from graphify-hook, so the example works unedited on every platform (tested on macOS and Windows).
.githooks/post-commit — rebuilds the graph after each commit. Enable with git config core.hooksPath .githooks.

To wire a different project, copy .claude/ (including settings.json.example → settings.json, editing the .exe suffix for your OS) and .mcp.json.example (as .mcp.json, no edits needed) into it.

Sharing a graph across machines / OSes

graph.json stores paths with forward slashes, so a graph extracted on one OS resolves on another (Windows / WSL-Linux / macOS). The graph itself doesn't depend on the OS that extracts it: every branch of a platform $if is kept, and CI checks that Linux, macOS and Windows extract identical graphs of the same V commit. A declaration only some builds compile records which, as a $if would write it ("build": "use_openssl ?" in graph.json), from its file's name (_d_use_openssl, _notd_use_openssl, _nix, _linux, _arm64) and the file-scope $if it is in, and a call in a function body the $if branches around it ("build" on the edge). A call through an alias that each build declares in its own file, such as ssl.SSLConn (mbedtls.SSLConn by default, openssl.SSLConn with -d use_openssl), links to each build's method. See FUTURE_WORK.md §12. All structural queries (query_graph, get_node, shortest_path, overview, skeleton) need only the graph file — no source. get_body reads the actual source, so on a different machine point it at the local checkout:

graphify body <symbol> --graph shared\graph.json --source-dir /path/to/local/checkout

For the MCP server, pass the local source root as a 2nd arg (or set GRAPHIFY_SOURCE_DIR):

{ "mcpServers": { "graphify": {
  "command": "…/graphify-mcp", "args": ["…/graph.json", "/path/to/local/checkout"] } } }

Status

Phase 1 (engine) — done; V only.

Known gaps and evidence-gated future work are recorded in FUTURE_WORK.md.

Name		Name	Last commit message	Last commit date
.claude		.claude
.githooks		.githooks
.github		.github
bench		bench
bin		bin
cmd		cmd
graphify		graphify
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json.example		.mcp.json.example
BENCH.md		BENCH.md
FUTURE_WORK.md		FUTURE_WORK.md
README.md		README.md
backend_common.v		backend_common.v
backend_v.v		backend_v.v
batch_proto.v		batch_proto.v
bundle.v		bundle.v
cache.v		cache.v
communities.v		communities.v
diff.v		diff.v
emit_cypher.v		emit_cypher.v
emit_graphml.v		emit_graphml.v
emit_json.v		emit_json.v
emit_skeleton.v		emit_skeleton.v
emit_svg.v		emit_svg.v
freshness.v		freshness.v
generics.v		generics.v
graph_html.v		graph_html.v
graph_ops.v		graph_ops.v
graphify.config.json.example		graphify.config.json.example
graphify.v		graphify.v
graphify_test.v		graphify_test.v
infer.v		infer.v
layer.v		layer.v
library.v		library.v
merge.v		merge.v
model.v		model.v
store.v		store.v
v.mod		v.mod
walker.v		walker.v
worktree.v		worktree.v

Navigation Menu

Repository navigation

About

Repository files navigation

graphify

Why

Measured savings

Design

Model

Emitters

Usage

MCP server (for Claude Code and Codex)

Claude Code

Codex

Operational scripts

`bin/update-vlang-graph.vsh` — scheduled graph refresh

`bin/switch-vlang-graph.vsh` — branch-aware graph switching

`bench/session_stats.vsh` — token-free MCP usage stats

`bench/extract_bench.vsh` — repeatable extraction benchmark

Scheduling — Windows / macOS / Linux

Claude Code wiring

Sharing a graph across machines / OSes

Status

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

graphify

Why

Measured savings

Design

Model

Emitters

Usage

MCP server (for Claude Code and Codex)

Claude Code

Codex

Operational scripts

bin/update-vlang-graph.vsh — scheduled graph refresh

bin/switch-vlang-graph.vsh — branch-aware graph switching

bench/session_stats.vsh — token-free MCP usage stats

bench/extract_bench.vsh — repeatable extraction benchmark

Scheduling — Windows / macOS / Linux

Claude Code wiring

Sharing a graph across machines / OSes

Status

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`bin/update-vlang-graph.vsh` — scheduled graph refresh

`bin/switch-vlang-graph.vsh` — branch-aware graph switching

`bench/session_stats.vsh` — token-free MCP usage stats

`bench/extract_bench.vsh` — repeatable extraction benchmark