mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-08-28 05:25:25 +00:00

Mirror of https://github.com/abhigyanpatwari/GitNexus.git

Find a file

Gergő Magyar 7316503ebc perf(analyze): hold structural relationships out of the JS heap, on by default (#2680 ) (#2685 ) * refactor(lbug): extract SyncCsvWriter into a shared module `PdgEmitSink` (#2202) declared `SyncCsvWriter` as a private, non-exported class. The structural streaming sink for #2680 needs the same buffered sync-write + poison/openFailure IO discipline, and importing it is not possible while it is module-private — so the alternative was copying ~90 lines of it. Extract the class (and the chunk-rows default it uses) into `sync-csv-writer.ts` and have `PdgEmitSink` import it. `DEFAULT_PDG_EMIT_CHUNK_ROWS` stays exported as an alias so no existing caller changes. Pure refactor: no behaviour change. pdg-emit-sink.ts 396 -> 302 lines; tsc clean; the 23 existing #2202 tests pass unchanged. Refs #2680 * feat(lbug): add GraphEmitSink for streaming structural relationship emit Structural sibling of PdgEmitSink (#2202): a KnowledgeGraph façade that routes relationships no mid-pipeline phase reads back to bounded CSV-on-disk and never stores them. Nothing constructs it yet. Measurement drove the design. On a kernel-shaped synthetic graph (400k nodes, 2.7 edges/node): nodes only ...... 367 B/node nodes + edges ... 2075 B/node <- reproduces the #2649 ~2.1 KB/node => the relationship layer is 83% of graph heap, ~646 B/edge so streaming relationships is where the memory is; nodes stay resident (they are 17%, and two scope-resolution index builders scan them). Dropping just the redundant relationshipsByType/edgeIdsByNode indexes was also measured — 174 of 648 B/edge, ~1.3x — and is not a substitute. RETAINED_REL_TYPES is derived from an exhaustive audit of every relationship read site under src/, and each entry names its reader. An earlier draft carried 14 types, 5 of which no reachable phase reads. Two deliberate departures from PdgEmitSink, both because its invariants do not hold here: - dedup by relationship id, since no upstream per-file uniqueness guarantee exists for structural edges and COPY would violate the PK; - removeRelationship on an already-streamed id throws instead of no-oping, so a mutating consumer cannot corrupt the graph undetected. Also exposes hasStreamedSemanticEdge for the local-symbol pruner: without it a block-local symbol referenced only by a streamed edge looks unreferenced and gets pruned, leaving a CSV row pointing at a node with no row. Refs #2680 * feat(analyze): stream structural relationships to CSV under GITNEXUS_STREAM_GRAPH_EMIT Wires GraphEmitSink into the pipeline behind a full-rebuild-only flag, so relationships that no mid-pipeline phase reads back never enter the JS heap. Measured ~2.9x reduction of graph heap: 0.17 (nodes) + 0.83 * 0.21 (retained edges) = 0.344 retained. This is a constant factor, NOT O(chunk) — node identity and the resolution registries stay O(repo). The sink is armed at the PARSE boundary, not at graph construction. An exhaustive audit of every relationship read site under src/ found four mid-pipeline CALLS consumers, not the two an earlier draft assumed: - local-symbol-pruner (full iterRelationships scan, then removeNode) - communities / processes (whole-graph forEachRelationship) - mapCobolToGraph, which scans CALLS and REMOVES the unresolved ones — and runs BEFORE parse, so streaming from construction would have silently stopped COBOL cross-program call resolution - taintSummaries, gated on `pdg` and NOT on `skipGraphPhases`, so it needs its own gate or --pdg + this flag yields an empty taint layer Accordingly communities, processes, taintSummaries and callSummaries are all disabled under the flag, and the run logs what it is giving up. Two fixes that are correct independently of the flag: - runPipelineFromRepo keyed its community/process extraction off `!skipGraphPhases` while getPhaseOutput THROWS on a phase filtered out by any enabledWhen predicate — now a presence check, so filtered combinations return undefined instead of crashing. - loadGraphToLbug COPYs one job per CSV FILE rather than per label pair. #2202's throw-on-collision merge is only sound because BasicBlock pairs are disjoint; a streamed CALLS edge is Function\|Function and always collides with the whole-graph CSV for that pair, so the structural manifest appends instead. The buffer-pool hint adds the streamed row count back in: the hint only ever shrinks the pool, so sizing it from the post-streaming relationshipCount would starve the COPY at exactly the scale this targets. detect_changes: 18 symbols / 10 files / 9 processes, all within the planned scope. Full suite green with the flag off. Refs #2680 * fix(mcp): stop impact() under-reporting risk on a streamed index An index built with streamed structural emit has no Process or Community rows, and impact()'s risk scorer uses processCount >= 5 and moduleCount >= 5 as two of its four CRITICAL escalation criteria. The missing-table errors are swallowed as benign without raising `partial`, so nothing distinguished 'this repo has no processes' from 'this index was built without them' — the same change would report LOW off a streamed index and CRITICAL off a complete one, with no signal either way. That is the false-clean shape #2283 ruled out for detect_changes, and it matters more here because the repo's own workflow mandates impact() before every symbol edit. Stamp `graphPhases: 'complete' \| 'skipped'` into RepoMeta and have impact() attach riskUnderstated + an explanatory riskNote when the index is stamped skipped, so the reported level is explicitly a lower bound. Unlike the rest of RepoMeta.capabilities this stamp has a real programmatic reader. Also documents GITNEXUS_STREAM_GRAPH_EMIT in the README env table, including everything the flag disables. Refs #2680 * test(lbug): differential set-identity gate for streamed structural emit The acceptance property for #2680: for the same node/edge set, the rows reaching the bulk COPY must be identical whether streaming is on or off. With streaming on they arrive from two places — the residual in-memory graph via streamAllCSVsToDisk, plus the sink's per-pair CSVs — so the test asserts their UNION equals the single whole-graph emit. Also asserts the split is real (retained + streamed == total, streamed > 0), so a sink that silently streamed nothing cannot pass the equality vacuously. Verified discriminating: with sink.arm() commented out the test fails ('expected 0 to be greater than 0'); restored, it passes. Fixture spans both sides of RETAINED_REL_TYPES and includes a self-edge and a duplicate relationship id — the cases where a naive sink diverges from the whole-graph emit. Drives the sink directly rather than running analyze, matching pdg-emit-streaming-roundtrip.test.ts: the guarantee is about emitted rows, and the worker pool would add unrelated machinery without strengthening the assertion. Refs #2680 * fix(test): remove literal NUL byte and cover streamGraphEmit phase gating Two review findings, both verified before accepting. 1. The round-trip test contained a literal NUL byte as a key separator, which made Git treat the whole .ts file as BINARY — `git show --numstat` reported `-\t-` for it, so the file would not diff or blame and CI text tooling would skip it. Replaced with the escaped \\u0000 sequence; behaviour is identical, the file is text again. (Found by the Codex swarm lane.) 2. buildPhaseList's four new streamGraphEmit gating predicates and the flag-off default path had no test that would fail on revert — two review lanes flagged this independently. Reversing any enabledWhen condition would have passed the suite silently, which matters because an ungated taintSummaries yields an empty taint layer rather than an error. Added four cases: the streamed run drops communities/processes/ taintSummaries/callSummaries; it keeps mro/di (their reads are all in RETAINED_REL_TYPES); the flag-off list is untouched; and skipGraphPhases still works independently. Refs #2680 * fix(analyze): don't leak a temp dir when streaming is off; correct two overclaims Three review findings, all verified before accepting. 1. `graphEmitCsvDir: resolveNativeSafeStorageDir(...)` was evaluated unconditionally inside the pipeline-options literal. On a Windows non-ASCII storage path that helper mkdtempSyncs a REAL directory, so every analyze leaked one temp dir even with the flag off. Now resolved only when streaming is active, matching how the PDG sibling resolves inside its own guard. This was the only finding affecting flag-off users. 2. The retain-set comment claimed 'the differential round-trip test is what catches drift'. It cannot. addRelationship PARTITIONS edges between the graph and the CSVs, and the union of a partition is invariant under where the partition line falls — so that test stays green no matter how RETAINED_REL_TYPES is drawn. Only the read-site audit protects the invariant, and the comment now says so and names the grep to re-run. 3. The ~2.9x figure assigned streamed edges a retained cost of zero, ignoring the sink's own streamedIds/streamedEndpoints Sets — and relationship ids are plain concatenations of both endpoint ids, not hashes. Review measured those Sets at ~35% of full per-edge retention, not the '~a tenth' assumed, putting the real figure nearer ~1.7-2.2x; a member-dense Java/C# repo lands lower still, since the retained structural spine is a larger share there than in the TypeScript census the 0.21 came from. Code comment and README now give a range and say plainly that no end-to-end measurement on a real repository exists yet. Refs #2680 * fix(mcp): disclose degraded risk in detect_changes; stop pinning the sink Two more review findings, both cross-lane corroborated. 1. detect_changes derives risk_level SOLELY from affected-process count, and a graphPhases:'skipped' index has zero Process rows by construction. The STEP_IN_PROCESS query then succeeds with zero rows, so queryDegraded stays false and the tool returns risk_level 'low', affected_count 0, with no partial marker — for every change, forever. That is a false-clean on the gate this repo mandates before every commit, and it is the same #2283 shape the previous commit fixed in impact() while leaving its sibling untouched. Now carries the same riskUnderstated + riskNote disclosure. 2. PipelineResult.graphEmitSink had zero readers — the pruner predicate and the manifest are both threaded elsewhere — but returning it kept the sink, and therefore its O(streamed-edges) id and endpoint Sets, reachable through the entire COPY/FTS/embedding phase. That is precisely the phase this feature exists to fit inside RAM, so the field actively worked against the change's purpose. Dropped. Refs #2680 * refactor(2680): one named capability, one risk helper, a shorter header Pure cleanup pass — no behaviour change, 66 tests across the six affected suites still green, and the round-trip test still fails when the sink is left un-started. Three things were untidy: 1. The phase layer reached the sink through TWO loose callbacks bolted onto PipelineContext (`armStreaming`, `hasStreamedSemanticEdge`) — two fields, two wiring lines, no name for the thing they belonged to. Replaced by one `graphEmit?: GraphEmitControl`, a two-method interface declared beside the sink. Phases now say what they mean: `ctx.graphEmit?.beginStreaming()`. Also renames `arm()` to `beginStreaming()`, which needs no comment to explain. 2. The degraded-index risk disclosure was copy-pasted into impact() and detect_changes() — two meta probes, two near-identical prose blocks, and two long comments restating the same reasoning. Now one `streamedIndexRiskDisclosure()` helper carrying the explanation once; each caller passes only the clause naming which count is structurally zero for it. Same file, 45 lines in / 45 out, with the duplication gone. 3. The sink's file header had grown into a changelog of my own review corrections ('this once assumed', 'review measured'). A reader does not care what an earlier draft believed. Rewritten to state the design argument once — relationships are ~83% of graph heap, so they are what streams; nodes are the other 17% and are scanned, so they stay — under headings, with the honest 'this is an estimate, ~1.7-2.2x, no real-repo measurement yet' caveat kept in full. Refs #2680 * feat(analyze): make streamed graph emit the default, with nothing traded away Streaming was opt-in because it disabled the four phases that consume the whole CALLS graph — communities, processes, taintSummaries, callSummaries. That made it unshippable as a default: query() is process-grouped and clusters/skill-gen are community-backed, so every index would have silently lost them. The sink now answers a COMPLETE relationship read. It keeps streamed edges as four parallel columns over an interned node table — sourceId, targetId, type, confidence — and iterRelationships/iterRelationshipsByType/ forEachRelationship/relationshipCount return the retained edges concatenated with those. Every consumer therefore sees the whole graph and no phase knows streaming happened. Four fields, not six, because an audit showed community-processor, process-processor, taint-summaries and the pruner read only those — none keys on rel.id. That matters: relationship ids are unique long strings, and retaining them is precisely what made a fully-columnar attempt LOSE to the object graph (measured 838 MB vs 822 MB). Ids stay out of the columns; a read synthesizes one, which is safe because buildRelRow never persists it. Consequently deleted, not merely disabled: - the four enabledWhen gates and the 'what you give up' warning; - the pruner's hasStreamedSemanticEdge predicate and its plumbing — a complete scan sees streamed edges, so the dangling-edge hazard is gone by construction rather than by compensation; - the whole degraded-index apparatus: the graphPhases RepoMeta stamp, streamedIndexRiskDisclosure, and the riskUnderstated markers on impact() and detect_changes(). Nothing degrades, so nothing needs disclosing. Default is ON for full rebuilds; GITNEXUS_STREAM_GRAPH_EMIT=0 (or an explicit option) is the escape hatch, for bisecting a suspected streaming fault rather than routine use. Incremental runs still refuse it — the writeback reads relationships back out of the in-memory graph. Measured A/B, 400k nodes / 1.08M edges, all edges streamable (worst case for this design): 823 MB -> 626 MB, ~1.3x, all 1.08M edges still visible. That is deliberately less than the ~2.9x the retained-share formula implies — losslessness costs the dedup Set and the columns. The earlier, bigger number was bought by disabling phases. README and the file header both state 1.3x measured; neither claims O(chunk). New coverage: reads are complete (proven discriminating — 3 tests fail when the streamed leg is removed), endpoints/confidence survive the round trip, per-type lookup finds streamed types, and every CALLS-consuming phase stays registered under the flag. Refs #2680 * docs(2680): pin the invariants the default-on change relies on Review follow-ups. No behaviour change except the id-uniqueness fix. - pipeline.ts returns the RAW graph, not the sink, and that is load-bearing: phases read the sink so their scans are complete, but loadGraphToLbug feeds this value to streamAllCSVsToDisk, whose iterator would then emit every streamed edge a SECOND time on top of the per-pair CSVs the sink already wrote. Returning the sink there silently doubles every streamed relationship in the persisted graph, so the reason is now written down at the return site. - Synthesized ids now carry the column index, making them unique even when two streamed edges share (type, source, target) and differ only in reason/step. Harmless today because no consumer keys on relationship id, but real ids are unique and the synthesized ones should match, so a future id-keyed consumer cannot silently collapse two edges. - Recorded WHY dropping reason/step is safe, which is not the same argument as for id: the persisted row keeps their true values because buildRelRow receives the original relationship on the way through, so only in-memory reads see the 'streamed' placeholder. The ACCESSES reason:'read'\|'write' distinction that MCP queries depend on therefore survives in the database. A future in-pipeline consumer needing either field must add a column rather than trust the placeholder. Also verified while chasing a review lead: removeNodesByFile has no production callers and removeNode has exactly one (the pruner), which reads through the sink and so sees streamed edges. The dangling-edge hazard the deleted hasStreamedSemanticEdge predicate used to compensate for is closed by construction, not by luck. Refs #2680 * fix(2680): fail loudly on a missing CSV dir, and guard the retain set Resolves both findings from the review of this branch. MEDIUM — pipeline.ts silently skipped streaming when `streamGraphEmit` was true but `graphEmitCsvDir` was absent. The CLI always supplies the dir, but streaming is on by DEFAULT now, and the callers that build PipelineOptions themselves (eval-server, MCP daemon, tests) are exactly the ones that would omit it — so they would ask for streaming, not get it, and still see a successful run. That is the silent-degraded-outcome shape the rest of this work exists to prevent, so it now throws with the resolution hint. Covered by a test asserting the rejection. LOW — RETAINED_REL_TYPES had no automated guard, and the round-trip test structurally cannot be one: addRelationship PARTITIONS edges between the graph and the CSVs, and a partition's union is invariant under where the line falls, so that test stays green for any partitioning including a wrong one. Drift there yields a silently incomplete mid-pipeline edge set, not a crash. Added a test that derives the required set by grepping every literal iterRelationshipsByType('X') under src/ and asserts the constant covers it, with CALLS as the documented exemption (taintSummaries reads it, which is why the sink answers a complete read rather than retaining it). Proven discriminating: removing EXTENDS from the constant fails with "expected [ 'EXTENDS' ] to deeply equal []". 128 tests green across the eight affected suites, including the index-lock suite that arrived with the #2677 merge. Refs #2680 * docs(2680): record the measured CPU cost, not just the memory win I measured memory before shipping and never measured time, which was a gap: reads now allocate, rebuilding objects instead of returning stored ones, and a real analyze does SIX full relationship scans (pruner, communities x2, processes x2, the taint fixpoint's CALLS pass). Same 400k-node / 1.08M-edge graph: heap 820 MB -> 623 MB (1.32x better) scans 96 ms -> 651 ms (6.8x WORSE) 6.8x on iteration is worth knowing, but the absolute number decides it: ~0.5 s here, ~2 s extrapolated to kernel scale, against an analyze measured in minutes — under 1% of wall-clock. The ~26M short-lived objects at kernel scale are young-generation churn (the cheap case), and being ~800 MB further from the heap ceiling matters more than the churn costs: #2649's cascade came from GC thrash NEAR the limit, not from allocation volume as such. Also names the first lever if these scans ever go hot — a per-type index over the columns, so iterRelationshipsByType stops scanning all streamed edges — and notes that it trades memory back, so it needs a measurement first. Refs #2680 * perf(2680): cut the iteration regression from 6.8x to 1.8x The memory win came with an unmeasured CPU cost. Iteration went from returning stored objects to rebuilding them, across the SIX full relationship scans an analyze performs (pruner, communities x2, processes x2, taint's CALLS pass). First measurement: 90 ms -> 651 ms, 6.8x worse. Fixed properly rather than documented away. Two causes, each measured before and after: 1. The ~150-character synthesized `id` was built eagerly on every read — 6.5M concatenations per analyze, for a field NO in-pipeline consumer reads. Isolating it (constant id) showed 436 ms of the 555 ms regression. Now a lazy prototype getter on a fixed-shape `StreamedRelationship` class: the string is built only if someone asks, and V8 keeps one hidden class across millions of instances. 2. Generator and iterator-protocol overhead on million-edge walks. `forEachRelationship` (community detection's form, called twice) now loops the columns directly, skipping both. `iterRelationships` keeps an iterator but reuses one result record — a hand-rolled version allocating a fresh {value, done} per edge measured WORSE than the generator (252 ms), which is why the obvious rewrite is not the one that shipped. heap 821 MB -> 623 MB (1.32x better) scans 90 ms -> 180 ms (was 651 ms) The residual ~90 ms is object allocation, 6.5M instances across six scans, and it is irreducible while the read API returns objects at all. The remaining fix for true parity is a field-wise callback passing sourceId/targetId/type/ confidence as primitives — all four hot consumers read only those — but that changes the KnowledgeGraph interface and its consumers, so it belongs in its own measured change rather than bolted on here. Refs #2680 * perf(2680): zero-allocation field scan brings iteration back to parity Third and final step on the iteration cost. The memory win had come with a 6.8x iteration regression; the previous commit cut that to 1.8x by making the synthesized id lazy and removing generator overhead. The residual was object allocation itself — 6.5M instances across the six full relationship scans an analyze performs — which no amount of tuning removes while the read API hands back objects. So the hot consumers stop asking for objects. Adds `KnowledgeGraph.forEachRelationshipFields`, which passes (sourceId, targetId, type, confidence) as primitives — exactly and only what every whole-graph scan reads. On the sink those come straight out of the columns, allocating nothing; on the object-based graph they are read off the stored relationship, so the flag-off path is unaffected. Converted the five whole-graph scans: community detection (x2), process extraction (x2), and the local-symbol pruner. `isFileDefinesEdge` now takes (type, sourceId) rather than a relationship. The taint fixpoint's by-type pass is left alone — one scan of six, and converting it would turn an indexed bucket lookup into a full scan on the object-based graph. heap 820 MB -> 623 MB (1.32x better) scans ~82 ms -> ~90 ms (was 651 ms; now parity within noise) Also deletes the pruner's `hasStreamedSemanticEdge` option, which has had no caller since the sink's reads became complete — a dead knob is worse than no knob. Verified: 104 tests across the eight affected suites, including the pruner's pipeline integration test (which needs the raised worker-ready timeout on this host; it passes cleanly with it and its failures are the known 5s handshake). Refs #2680 * perf(2680): compact dedup keys — 1.32x -> 1.59x, speed unchanged An audit of where duplicate relationship ids actually come from, then the saving it unlocked. The audit (instrumented analyze of this repo): 25 duplicate-id hits across 63,412 streamed edges — 0.04%, all CALLS, every one the SAME call site re-emitted when a file is resolved in more than one language pass. Three things follow, and they rule out the cheap options: - dedup cannot be dropped (25 != 0, and a duplicate reaching COPY is a wrong graph); - it cannot move to row contents, because emit-references builds ids as `...->target:line:col`, so two calls between the same pair at different sites have byte-identical CSV rows that the whole-graph emit keeps; - it cannot move to a per-file source guard like `pdgEmittedFiles`, because a later language pass can resolve genuinely NEW edges for the same file. What was left was the key itself. An id embeds both node ids in full (~200 chars here) while the endpoints are ALREADY interned for the columns, so the Set was storing them twice. Keys are now built from the interner indices plus the id's trailing disambiguator parsed into NUMBERS. Numbers, not substrings, and that is load-bearing: a key built by slicing inside a long string is a V8 sliced/cons string that keeps its parent alive, so the id would never be freed and the saving would silently fail to appear. An earlier attempt at this measured no improvement for exactly that reason. Unrecognized id shapes (`rel:contains:` has no tail) fall back to storing the id verbatim — correctness first, saving second. heap 821 MB -> 518 MB (1.59x, was 1.32x) scans ~83 ms -> ~88 ms (parity, unchanged) Speed is untouched by construction: dedup is on the WRITE path, and none of the six full scans reads it. Also fixes removeRelationship, which the test suite caught: it looked up the raw id in a Set that now holds compact keys, so it silently stopped throwing on an already-streamed edge. It cannot recompute a key from a bare id, so it is now conservative — anything the real graph does not hold is treated as possibly-streamed once streaming has begun and fails loudly. A genuinely-absent id throws where main returns false; acceptable because the only production caller (the COBOL resolver) runs before the sink is armed. 89 tests green across the six affected suites. Refs #2680 * fix(2680): dedup key dropped edges when tail segment counts differed Both findings from the review of this branch, and the coverage gap named alongside them. HIGH — the compact dedup key packed the id's trailing numeric segments as `\|${a}\|${b}`, with `b` defaulting to 0 when only one segment was present and the segment COUNT absent from the key. So `:7` and `:7:0` produced the same key and the second edge was silently discarded as a duplicate: a lost relationship, no error, no warning. Found by probe, not by reading — two distinct ids for one (source, target, type) went in and one edge came out. The key now carries `seen`. Nothing existing caught it. The round-trip test compares the UNION of graph and CSV rows, and a dropped edge is missing from both, so it stayed green; the duplicate test only feeds a genuinely identical id, which is the case that SHOULD collapse. Four new cases pin the boundary instead: differing segment counts stay distinct, two call sites between one pair stay distinct (the `:line:col` shape from emit-references), a truly repeated id still collapses, and a non-numeric tail falls back to the full id. Proven discriminating — reverting the fix fails with "expected 1 to be 2". This costs ~66 MB at 400k nodes / 1.08M edges (584 MB, was 518 MB), so the heap win is 1.40x rather than 1.59x. Not a trade worth making the other way: a silently missing relationship is the exact failure class the rest of this work exists to prevent. I am not asserting a mechanism for why two extra characters per key cost that much — it is stable and reproducible across runs, and inventing a cause is how I got the earlier cons-string diagnosis wrong. LOW — removeRelationship throws for an absent id once streaming has begun, where KnowledgeGraph.removeRelationship returns false. The behaviour is deliberate (a bare id cannot be turned back into a compact key, and answering "false" for an edge already on disk is the worse failure) but it was undocumented and untested. Now stated on the interface itself and pinned by two cases: absent-id-while-streaming throws, absent-id-before-streaming returns false. Coverage gap — added a test asserting forEachRelationshipFields yields the same (source, target, type, confidence) tuples as iterRelationships. That guards the five whole-graph scans converted in `9fa18384`, where a divergence would silently skew community detection, process extraction and the pruner. Also records the verified scaling in the file header: linear at 100k/200k/ 400k/800k nodes, per-edge scan cost flat at ~13 ns in both arms, heap ratio drifting only 1.7x -> 1.5x as interner indices gain digits. No super-linear term. 135 tests green across the eight affected suites. Refs #2680 --------- Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com>		2026-07-25 07:43:51 +01:00
.agents/plugins	feat: full Codex support — hooks, plugin marketplace, and setup (#2328 , supersedes #1131 ) (#2369 )	2026-07-04 13:32:17 +01:00
.claude	fix: index staleness — false-stale status after analyze (#2668 ) + inline staleness in query/context/impact/cypher tools (#2655 ) (#2683 )	2026-07-25 07:21:44 +01:00
.claude-plugin	chore: release v1.6.9 (#2367 )	2026-07-04 07:53:06 +01:00
.cursor	fix(storage): rename index metadata to gitnexus.json with dual-write compatibility (#2363 )	2026-07-03 19:32:59 +01:00
.devcontainer	docs: restructure root README, fact-check all READMEs (#2360 )	2026-07-03 08:46:59 +01:00
.gemini/commands	feat(review): add PR reviewer swarm agents (#1851 )	2026-05-29 18:24:16 +01:00
.github	fix(scope-resolution): gate C#/Kotlin free calls by instance ownership (#2563 ) (#2654 )	2026-07-24 13:31:56 +01:00
.history/gitnexus	fix(test): add --repo to CLI e2e tool tests for multi-repo environment	2026-03-18 08:12:25 +00:00
.husky	feat: configure prettier with pre-commit hook (#563 )	2026-03-28 14:58:04 +00:00
.sisyphus/drafts	fixed constructor to method relation not getting stored in kuzu issue	2026-01-26 22:58:15 +05:30
deploy/kubernetes	ci(docker): mirror signed images to Docker Hub alongside GHCR (#1029 )	2026-04-23 18:59:26 +01:00
Documentation	Add Kilo Code + GitNexus MCP setup guide (#2259 )	2026-07-02 11:04:22 +01:00
eslint-rules	fix(windows): 32767-char tree-sitter crash + VECTOR extension SIGSEGV (#1433 )	2026-05-10 16:00:36 +01:00
eval	fix(eval): give vitest a writable .vite-temp inside read-only dependency mounts (#2630 )	2026-07-22 10:16:25 +01:00
gitnexus	perf(analyze): hold structural relationships out of the JS heap, on by default (#2680 ) (#2685 )	2026-07-25 07:43:51 +01:00
gitnexus-claude-plugin	fix: index staleness — false-stale status after analyze (#2668 ) + inline staleness in query/context/impact/cypher tools (#2655 ) (#2683 )	2026-07-25 07:21:44 +01:00
gitnexus-cursor-integration	feat(ci): review agent runs as a coordinated reviewer swarm (#2572 )	2026-07-20 07:31:40 +01:00
gitnexus-shared	fix(scope-resolution): gate C#/Kotlin free calls by instance ownership (#2563 ) (#2654 )	2026-07-24 13:31:56 +01:00
gitnexus-test-setup	feat: merge gitnexus-mcp into gitnexus package - unified CLI+MCP	2026-02-04 01:12:41 +05:30
gitnexus-web	Merge pull request #2643 from abhigyanpatwari/dependabot/npm_and_yarn/gitnexus-web/lru-cache-11.5.2	2026-07-23 11:56:12 +05:30
pr-swarm-review	feat(skills): GitNexus Engineering Tool Kits (#2566 )	2026-07-19 15:07:24 +01:00
.cursorrules	docs: agent development framework, GitHub templates, eval refactor (#479 )	2026-03-25 06:48:41 +00:00
.dockerignore	fix(ci): Change docker base image from alpine to debian (#1014 )	2026-04-21 21:31:58 +01:00
.env.example	feat(analyze): private GitHub repos via PAT + Azure DevOps Server support (#2076 , #2210 ) (#2223 )	2026-06-16 05:49:02 +01:00
.git-blame-ignore-revs	feat: configure eslint with unused import removal (#564 )	2026-03-28 15:28:09 +00:00
.gitattributes	feat(devcontainer): add devcontainer for Claude/Codex/Cursor CLIs (#1875 )	2026-06-02 05:09:01 +01:00
.gitignore	chore: stop tracking docs/plans (planning output stays local)	2026-07-21 10:09:35 +00:00
.gitleaks.toml	feat(analyze): private GitHub repos via PAT + Azure DevOps Server support (#2076 , #2210 ) (#2223 )	2026-06-16 05:49:02 +01:00
.gitleaksignore	chore(security): suppress deleted auth placeholder	2026-07-16 10:08:59 +07:00
.mcp.json	fix: use cross-platform npx command in .mcp.json	2026-02-22 17:46:04 +00:00
.prettierignore	chore(quality): exclude test/fixtures from CodeQL, ESLint, and Prettier (#1313 )	2026-05-04 09:35:34 +01:00
.prettierrc	feat: configure prettier with pre-commit hook (#563 )	2026-03-28 14:58:04 +00:00
.windsurfrules	resources implemented and agents.md and skills updated to use it	2026-02-05 05:13:48 +05:30
AGENTS.md	feat(ci): review agent runs as a coordinated reviewer swarm (#2572 )	2026-07-20 07:31:40 +01:00
ARCHITECTURE.md	fix(scope-resolution): resolve callable reference flows (#2437 ) (#2522 )	2026-07-17 17:20:02 +01:00
CHANGELOG.md	perf(hooks): cmdline-first Linux db-lock scan, drop the lsof fallback (#2180 ) (#2183 )	2026-06-13 11:52:14 +01:00
CLAUDE.md	feat(ci): review agent runs as a coordinated reviewer swarm (#2572 )	2026-07-20 07:31:40 +01:00
compound-engineering.local.md	feat: Phase 7 type resolution — return-aware loop inference & PHP class-property iterables (#341 )	2026-03-18 08:39:38 +00:00
CONTRIBUTING.md	ci: move Node pins to the 22.18 floor	2026-07-21 10:09:34 +00:00
docker-compose.yaml	feat(web): support GITNEXUS_BACKEND_URL env var for Docker deployments (#1286 )	2026-05-25 11:21:11 +01:00
docker-server.mjs	feat(web): support GITNEXUS_BACKEND_URL env var for Docker deployments (#1286 )	2026-05-25 11:21:11 +01:00
docker-server.test.mjs	feat(web): support GITNEXUS_BACKEND_URL env var for Docker deployments (#1286 )	2026-05-25 11:21:11 +01:00
Dockerfile.cli	fix(docker): ship runtime-needed published assets (hooks/, skills/) into the image (#2130 ) (#2132 )	2026-06-10 08:38:37 +01:00
Dockerfile.web	fix(security): Pin Docker Node base images, remove runtime package-manager CVE surface, verify Trivy on PRs, and harden Dependabot policy (#1455 )	2026-05-09 16:55:31 +01:00
DoD.md	feat(skills): GitNexus Engineering Tool Kits (#2566 )	2026-07-19 15:07:24 +01:00
eslint.config.mjs	fix(windows): 32767-char tree-sitter crash + VECTOR extension SIGSEGV (#1433 )	2026-05-10 16:00:36 +01:00
GUARDRAILS.md	fix: make large incremental writebacks commit reliably (#2409 ) (#2425 )	2026-07-10 14:05:23 +01:00
LICENSE	docs: update license copyright holder	2026-02-03 22:54:01 +05:30
llms.txt	docs: agent development framework, GitHub templates, eval refactor (#479 )	2026-03-25 06:48:41 +00:00
MIGRATION.md	fix(storage): rename index metadata to gitnexus.json with dual-write compatibility (#2363 )	2026-07-03 19:32:59 +01:00
package-lock.json	chore(deps-dev): bump the npm_and_yarn group across 1 directory with 2 updates (#2621 )	2026-07-21 22:43:34 +01:00
package.json	feat(package): add gitnexus commands for analysis	2026-04-29 16:37:06 +03:00
README.md	Merge remote-tracking branch 'upstream/main'	2026-07-23 14:50:09 +08:00
RUNBOOK.md	fix(storage): rename index metadata to gitnexus.json with dual-write compatibility (#2363 )	2026-07-03 19:32:59 +01:00
SECURITY.md	ci(security): add automated security and vulnerability scans (#1297 )	2026-05-04 08:21:53 +01:00
skills.mdm	FEAT: Added support for optional skill generation based on KuzuDB after initial repo analysis (npx gitnexus analyze --skills) (#171 )	2026-03-13 08:29:13 +00:00
swift-ingestion-gaps.md	docs: add macro declarations to Swift ingestion gaps	2026-03-23 14:21:32 +01:00
TESTING.md	refactor(ingestion): delete legacy call-resolution DAG + heritage processor (RING4-1, #942 ) (#2023 )	2026-06-04 11:07:37 +01:00
type-resolution-roadmap.md	feat: implement cross-file binding propagation for multiple languages	2026-03-21 07:47:04 +00:00
type-resolution-system.md	feat(ingestion): TypeScript registry-primary scope resolution (Ring 3) (#1050 )	2026-04-26 08:23:08 +01:00

README.md

GitNexus

⚠️ Important Notice: GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is not affiliated with, endorsed by, or created by this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.

The nervous system for agent context.

Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart MCP tools so AI agents never miss code.

💬 Discord · 🌐 Web UI · 🏢 Enterprise (SaaS & self-hosted)

https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72

Like DeepWiki, but deeper. DeepWiki helps you understand code. GitNexus lets you analyze it — a knowledge graph tracks every relationship, not just descriptions.

TL;DR: The CLI + MCP makes your AI agent reliable — it gives Cursor, Claude Code, Antigravity, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity. The Web UI is a quick way to chat with any repo in the browser.

Quick Start

# 1. Index your repo (run from repo root)
npx gitnexus analyze

# 2. Connect your editors (one-time, auto-detects Claude Code, Cursor, Codex, …)
npx gitnexus setup

That's it. analyze indexes the codebase, installs agent skills, registers Claude Code hooks, and creates AGENTS.md / CLAUDE.md context files — all in one command. setup writes the MCP config so your AI agent can use the graph.

Install problems? npm 11 crash · slow cold install · no C++ toolchain

On npm 11.x? npx can crash during install with Cannot destructure property 'package' of 'node.target' (an npm/arborist bug, before GitNexus runs). Use pnpm instead — it builds the native deps explicitly:
pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze
Or install globally (npm install -g gitnexus@latest) and run gitnexus analyze. See #1939.

Fastest MCP startup: install globally (npm i -g gitnexus) before running gitnexus setup — this writes an absolute-path MCP config that bypasses npx entirely. On a cold cache, an npx-based MCP install can exceed Claude Code's MCP_TIMEOUT default (~30s).

No C++ toolchain? Set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 before npm install -g gitnexus to skip the vendored grammar materialize/build for tree-sitter-dart, tree-sitter-proto, tree-sitter-swift, and tree-sitter-kotlin — those four languages won't be parsed, but install completes in seconds without python3/make/g++. Strict =1 only — any other value falls through to the rebuild.

Behind an HTTP proxy / regional firewall? onnxruntime-node's postinstall downloads optional CUDA binaries from api.nuget.org and ignores HTTP_PROXY/HTTPS_PROXY (#2370). The embedding stack is an optional dependency, so a failed download no longer breaks the install — and it self-heals: the first gitnexus analyze --embeddings (or gitnexus embeddings install) fetches the stack through your npm registry config (mirrors/proxies apply, no NuGet) into ~/.gitnexus/embedding-runtime (override with GITNEXUS_EMBEDDING_RUNTIME_DIR). The on-demand prefix needs Node with module.registerHooks (≥ 22.15 on 22.x, ≥ 23.5 on 23.x); on older Node, keep the stack in the install itself with ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus (works on every supported Node).

About tree-sitter-kotlin: like Dart/Proto/Swift, Kotlin is a vendored grammar (under gitnexus/vendor/tree-sitter-kotlin). Upstream ships source only (no prebuilt binaries), so GitNexus cross-builds the platform prebuilds itself (via the build-tree-sitter-prebuilds GitHub Actions workflow) and vendors them — the same uniform pipeline used for Dart, Proto, and Swift. node-gyp-build selects the right .node at require time, so no C/C++ toolchain is needed. If no prebuild matches your platform-arch, only Kotlin (.kt/.kts) parsing is unavailable; the rest of gitnexus is unaffected.

Two Ways to Use GitNexus

	CLI + MCP (recommended)	Web UI
What	Index repos locally, connect AI agents via MCP	Visual graph explorer + AI chat in browser
For	Daily development with Cursor, Claude Code, Antigravity, Codex, Windsurf, OpenCode	Quick exploration, demos, one-off analysis
Scale	Full repos, any size	Limited by browser memory (~5k files), or unlimited via backend mode
Install	`npm install -g gitnexus`	No install — gitnexus.vercel.app
Storage	LadybugDB native (fast, persistent)	LadybugDB WASM (in-memory, per session)
Parsing	Tree-sitter native bindings	Tree-sitter WASM
Privacy	Everything local, no network	Everything in-browser, no server

Bridge mode: gitnexus serve connects the two — the web UI auto-detects the local server and can browse all your CLI-indexed repos without re-uploading or re-indexing.

Why a Knowledge Graph?

Tools like Cursor, Claude Code, Codex, Cline, Roo Code, and Windsurf are powerful — but they don't truly know your codebase structure. So this happens:

AI edits UserService.validate()
Doesn't know 47 functions depend on its return type
Breaking changes ship

Traditional Graph RAG gives the LLM raw graph edges and hopes it explores enough. GitNexus precomputes structure at index time — clustering, tracing, scoring — so tools return complete context in one call:

flowchart TB
    subgraph Traditional["Traditional Graph RAG"]
        direction TB
        U1["User: What depends on UserService?"]
        U1 --> LLM1["LLM receives raw graph"]
        LLM1 --> Q1["Query 1: Find callers"]
        Q1 --> Q2["Query 2: What files?"]
        Q2 --> Q3["Query 3: Filter tests?"]
        Q3 --> Q4["Query 4: High-risk?"]
        Q4 --> OUT1["Answer after 4+ queries"]
    end

    subgraph GN["GitNexus Smart Tools"]
        direction TB
        U2["User: What depends on UserService?"]
        U2 --> TOOL["impact UserService upstream"]
        TOOL --> PRECOMP["Pre-structured response:
        8 callers, 3 clusters, all 90%+ confidence"]
        PRECOMP --> OUT2["Complete answer, 1 query"]
    end

Core innovation: Precomputed Relational Intelligence

Reliability — the LLM can't miss context; it's already in the tool response
Token efficiency — no 10-query chains to understand one function
Model democratization — smaller LLMs work because the tools do the heavy lifting

What Your AI Agent Gets

17 MCP tools (15 per-repo + 2 group)

Tool	What It Does
`list_repos`	Discover all indexed repositories (paginated — `limit`/`offset`)
`query`	Process-grouped hybrid search (BM25 + semantic + RRF)
`context`	360-degree symbol view — categorized refs, process participation
`impact`	Blast radius analysis with depth grouping and confidence
`trace`	Shortest directed path between two symbols (call + class-member edges)
`detect_changes`	Git-diff impact — maps changed lines to affected processes
`check`	Read-only structural checks against the indexed graph
`rename`	Multi-file coordinated rename with graph + text search
`cypher`	Raw Cypher graph queries
`route_map`	API route map — which components fetch which endpoints, and handlers
`tool_map`	MCP/RPC tool definitions — where they're defined and handled
`shape_check`	Validate API response shapes against consumers' property accesses
`api_impact`	Pre-change impact report for an API route handler
`explain`	Explain persisted taint findings (source→sink flows, `--pdg` indexes)
`pdg_query`	Query control/data dependence at statement level (`--pdg` indexes)
`group_list`	List configured repository groups
`group_sync`	Rebuild a group's Contract Registry and cross-repo links

Per-repo tools take an optional repo parameter (omit it when only one repo is indexed) and an optional branch for indexes pinned with gitnexus analyze --branch. Omitting branch queries the workspace index, which follows your checked-out working tree — switching branches and re-running gitnexus analyze updates it incrementally. explain and pdg_query need an index built with gitnexus analyze --pdg.

Resources for instant context

Resource	Purpose
`gitnexus://repos`	List all indexed repositories (read this first)
`gitnexus://setup`	Setup and usage guidance for agents
`gitnexus://repo/{name}/context`	Codebase stats, staleness check, and available tools
`gitnexus://repo/{name}/clusters`	All functional clusters with cohesion scores
`gitnexus://repo/{name}/cluster/{name}`	Cluster members and details
`gitnexus://repo/{name}/processes`	All execution flows
`gitnexus://repo/{name}/process/{name}`	Full process trace with steps
`gitnexus://repo/{name}/schema`	Graph schema for Cypher queries
`gitnexus://group/{name}/contracts`	A group's extracted contracts and cross-links
`gitnexus://group/{name}/status`	Staleness of repos in a group

2 MCP prompts for guided workflows

Prompt	What It Does
`detect_impact`	Pre-commit change analysis — scope, affected processes, risk level
`generate_map`	Architecture documentation from the knowledge graph with mermaid diagrams

Agent skills installed to `.claude/skills/` and `.agents/skills/` (if `.agents/` exists) automatically

Exploring — navigate unfamiliar code using the knowledge graph
Debugging — trace bugs through call chains
Impact Analysis — analyze blast radius before changes
Refactoring — plan safe refactors using dependency mapping
Guide — GitNexus tool/resource/schema reference for the agent
CLI — run analyze/status/clean/wiki commands on request
PDG Query — statement-level control/data dependence queries (--pdg index)
Taint Analysis — source→sink data-flow findings (--pdg index)
Plan (/gitnexus-plan) — implementation-ready engineering plans backed by the graph and PDG slices
Work (/gitnexus-work) — executes a plan as impact-checked, detect_changes-gated atomic commits
Review (/gitnexus-review) — graph-backed review of a PR, branch, range, or local diff, with taint pass and per-domain expert lenses
LFG (/gitnexus-lfg) — the full pipeline: plan → user gate → work → review

Repo-specific skills — run gitnexus analyze --skills and GitNexus detects the functional areas of your codebase (via Leiden community detection) and generates each one as a direct project skill under .claude/skills/gitnexus-area-<name>/. Each skill describes a module's key files, entry points, execution flows, and cross-area connections, and is regenerated on each --skills run to stay current.

When a repo contains an .agents/ directory, the standard and generated skills are also mirrored to .agents/skills/ (e.g. .agents/skills/gitnexus-cli/, .agents/skills/gitnexus-area-<name>/) so agents that read repo-local .agents/skills/ (like Codex) stay in sync.

Editor Setup

gitnexus setup auto-detects your editors and writes the correct global MCP config. Run it once. To configure only selected integrations, pass --coding-agent/-c with a comma-separated list, e.g. gitnexus setup -c cursor,codex.

Editor	MCP	Skills	Hooks (auto-augment)	Support
Claude Code	Yes	Yes	Yes (PreToolUse + PostToolUse)	Full
Cursor	Yes	Yes	Yes (postToolUse, manual install)	Full
Antigravity (Google)	Yes	Yes	Yes (AfterTool, Gemini CLI hooks schema)¹	Full
Codex	Yes	Yes	Yes (PreToolUse + PostToolUse, Codex hooks)	Full
OpenCode	Yes	Yes	—	MCP + Skills
CodeBuddy (Tencent)	Yes	Yes	—	MCP + Skills
Qoder (Alibaba)	Yes	Yes	—	MCP + Skills
Windsurf	Yes	—	—	MCP

Claude Code and Codex get the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.

¹ Antigravity hooks follow the Gemini CLI hooks reference (Antigravity 2.0 is the documented successor to Gemini CLI). Augmentation runs in AfterTool because BeforeTool has no context-injection channel in the Gemini contract — the agent sees graph context appended to the tool result via hookSpecificOutput.additionalContext. Stale-index hints land in the same channel after a successful git commit/merge/rebase/cherry-pick/pull. The schema may evolve if Antigravity-specific hook docs diverge from Gemini CLI's; the implementation will track those changes.

Manual MCP configuration (if you prefer not to run gitnexus setup)

Claude Code (full support — MCP + skills + hooks):

# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

Codex (full support — MCP + skills + hooks):

codex mcp add gitnexus -- npx -y gitnexus@latest mcp

Or via ~/.codex/config.toml (system scope) / .codex/config.toml (project scope):

[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]

Codex hooks (PreToolUse graph enrichment + PostToolUse stale-index detection in ~/.codex/hooks.json, same schema as Claude Code) need the bundled adapter script, so they are installed by gitnexus setup -c codex rather than manually.

Alternatively, install everything as a Codex plugin (MCP + skills + hooks in one step):

codex plugin marketplace add abhigyanpatwari/GitNexus
# then inside Codex: /plugins → install "GitNexus"

Codex notes: SessionStart is intentionally not registered — Codex reads AGENTS.md natively, which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via /hooks before they run. Pick one install route (gitnexus setup -c codex or the plugin): plugin hooks load alongside ~/.codex/hooks.json, so installing both can fire duplicate hooks per tool call.

Cursor (~/.cursor/mcp.json — global, works for all projects):

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Antigravity (Google) — ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

gitnexus setup also merges an AfterTool entry into ~/.gemini/settings.json (under the canonical Gemini CLI hooks schema) and installs skills to ~/.gemini/antigravity/skills/. Existing user hooks are preserved. The hook adapter's path is rewritten at install time, so run gitnexus setup rather than hand-editing.

OpenCode (~/.config/opencode/config.json):

{
  "mcp": {
    "gitnexus": {
      "type": "local",
      "command": ["gitnexus", "mcp"]
    }
  }
}

CodeBuddy (Tencent) — priority chain, edit the first non-empty file that exists: ~/.codebuddy/.mcp.json (recommended) → ~/.codebuddy/mcp.json (deprecated) → ~/.codebuddy.json (legacy). CodeBuddy reads only the first existing file, so adding servers to a higher-priority file than the one currently in use would hide the servers below it. Create ~/.codebuddy/.mcp.json only if none exist:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Qoder (Alibaba) — ~/.qoder.json:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

MCP read-only mode

Set GITNEXUS_MCP_READ_ONLY=1 before starting the MCP server to expose only the proven single-repository read surface. Raw cypher, rename and group tools, group routing, and group resources are omitted from discovery and rejected before backend dispatch. Tool descriptions and generated setup/context resources are scrubbed so they do not recommend unavailable routes.

The default is unchanged when the variable is unset or 0. Any other value fails server startup rather than silently weakening the policy.

MCP repository policy

Set GITNEXUS_MCP_ALLOWED_REPOS to a comma-separated list of canonical registry names or absolute indexed paths. Entries are trimmed, resolved against the registry, and deduplicated at startup. When exactly one repository is allowed it becomes the implicit default; when several are allowed, callers must select one unless GITNEXUS_MCP_DEFAULT_REPO is also set.

The default repository must resolve to an allowed repository. Invalid, ambiguous, blank, or mismatched configuration fails startup before stdio or HTTP begins serving. The allowlist applies to tools, aliases, discovery, resources, templates, implicit resolution, and embedded HTTP; hidden repository details are not included in selection errors. Setting only GITNEXUS_MCP_DEFAULT_REPO chooses a default without restricting explicit repository selections. An allowed repository whose name is duplicated in the registry must be configured by path, and its context resource is only served for the unique name form.

MCP response budgets

The query, context, and impact tools accept an optional positive-integer maxTokens argument. It bounds the complete formatted MCP response, including hints and error text, using a deterministic four-UTF-8-bytes-per-token estimate. When truncation is required, the response ends with … and remains valid UTF-8.

Set GITNEXUS_MCP_DEFAULT_MAX_TOKENS to apply the same guardrail when callers do not send maxTokens. An explicit tool argument takes precedence. Leaving both unset preserves the existing response byte-for-byte; this is a transport guardrail, not semantic pagination or an exact model-specific tokenizer limit.

CLI Reference

Everyday commands:

gitnexus setup                   # Configure MCP for detected editors (one-time; -c to select)
gitnexus analyze [path]          # Index a repository (or update a stale index)
gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
gitnexus eval-server             # Start lightweight evaluation HTTP tools (loopback by default)
gitnexus list                    # List all indexed repositories
gitnexus status                  # Show index status for current repo
gitnexus clean                   # Delete index for current repo
gitnexus wiki [path]             # Generate repository wiki from knowledge graph
gitnexus uninstall               # Preview removal of GitNexus MCP/skills/hooks (--force to apply)

You can also query the graph directly from the terminal — gitnexus query, context, impact, trace, cypher, detect-changes, and check mirror the MCP tools of the same names, and gitnexus doctor prints runtime platform capabilities.

Authenticated eval-server binding

gitnexus eval-server binds to 127.0.0.1 by default. Loopback bindings do not require authentication. Any non-loopback bind, including 0.0.0.0, a LAN address, or a hostname that resolves to a LAN IPv4 address, requires GITNEXUS_AUTH_TOKEN. Every endpoint then requires an exact Authorization: Bearer <token> header.

GITNEXUS_AUTH_TOKEN='replace-me' gitnexus eval-server --host 0.0.0.0

The token may be set in the shell, .env.local, or .env in the working directory. Precedence is shell > .env.local > .env. Only GITNEXUS_AUTH_TOKEN is read from those files; their other values are not added to the process environment. Keep token files uncommitted.

All analyze flags

gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
gitnexus analyze --embeddings [limit]  # Enable embedding generation (slower, better search)
gitnexus analyze --skip-agents-md   # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
gitnexus analyze --skip-skills      # Skip installing standard skill files under .claude/skills/ and .agents/skills/
gitnexus analyze --skip-git         # Index folders that are not Git repositories
gitnexus analyze --default-branch develop  # Branch used in the generated regression-compare example (base_ref)
gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
gitnexus analyze --workers <n>   # Parse worker pool size (>=1; default: cores-1, capped at 16,
                                 # auto-sized to the repo). 0 is rejected — there is no sequential mode.
gitnexus analyze --wal-checkpoint-threshold 67108864  # LadybugDB WAL auto-checkpoint threshold in bytes
                                 # (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)

If analyze reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use --worker-timeout 60 or set GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000. For very large files, GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES controls the worker job byte budget.

Embeddings node limit — gitnexus analyze --embeddings generates semantic search vectors with a default 50,000-node safety cap to protect memory on large repositories:

gitnexus analyze --embeddings          # default 50,000 node safety cap
gitnexus analyze --embeddings 0        # disable the cap entirely
gitnexus analyze --embeddings 100000   # custom cap

If embeddings are skipped on a large repository, the indexed graph likely exceeds the default cap — re-run with --embeddings 0 or a higher limit.

Repository groups (multi-repo / monorepo service tracking)

gitnexus group create <name>                           # Create a repository group
gitnexus group add <group> <groupPath> <registryName>  # Add a repo. <groupPath> is a hierarchy path
                                                       # (e.g. hr/hiring/backend); <registryName> is the
                                                       # repo's name from the registry (see `gitnexus list`)
gitnexus group remove <group> <groupPath>              # Remove a repo by its hierarchy path
gitnexus group list [name]                             # List groups, or show one group's config
gitnexus group sync <name>                             # Extract contracts and match across repos/services
gitnexus group contracts <name>                        # Inspect extracted contracts and cross-links
gitnexus group query <name> <q>                        # Search execution flows across all repos in a group
gitnexus group status <name>                           # Check staleness of repos in a group
gitnexus group impact <name> --target <symbol> --repo <groupPath>  # Cross-repo blast radius

Project config (.gitnexusrc)

Commit a .gitnexusrc JSON file at the repo root to preconfigure recurring analyze options per project, instead of re-passing the same flags every run. It is read from the resolved repo root (not .gitnexus/, which is gitignored index storage). CLI flags always override .gitnexusrc.

{
  // Default branch used in the generated regression-compare example (base_ref).
  // Use this so a project on `develop`/`master` doesn't get "main" rewritten
  // over its fix on every analyze. (Alias: "branch".)
  "defaultBranch": "develop",
  "skipContextFiles": true, // alias of skipAgentsMd: keep your own AGENTS.md/CLAUDE.md
  "skipSkills": true, // don't install standard skill files under .claude/skills/ and .agents/skills/
  "embeddings": true, // generate embeddings by default
  "workerTimeout": 60,
}

A nested analyze block is also accepted (and overrides flat keys for the same option):

{ "analyze": { "defaultBranch": "develop", "skipSkills": true } }

Notes:

The default branch is resolved as: --default-branch > .gitnexusrc defaultBranch/branch > auto-detected origin/HEAD > main.
skipContextFiles / skipAiContext are aliases for skipAgentsMd — they skip the AGENTS.md / CLAUDE.md block only. They do not imply skipSkills. indexOnly is the stronger option that skips all file injection.
Supported keys: defaultBranch (branch), skipAgentsMd (skipContextFiles, skipAiContext), skipSkills, indexOnly, stats/noStats, embeddings, dropEmbeddings, name, allowDuplicateName, maxFileSize, workerTimeout, walCheckpointThreshold, workers, embeddingThreads, embeddingBatchSize, embeddingSubBatchSize, embeddingDevice.
The file is JSON only. Unknown keys and invalid values fail fast with an actionable error before analysis starts.

Environment variables

Most analyze knobs are also CLI flags (--workers, --worker-timeout, --max-file-size, --verbose). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over env vars; env vars take precedence over built-in defaults.

Variable	Default	Effect	Tune when…
`GITNEXUS_WORKER_POOL_SIZE`	`cores - 1`, capped at 16	Parse worker pool size (must be ≥ 1). Equivalent to `--workers <n>`. The worker pool is the sole parse path — there is no sequential parser, so `0` is rejected with an actionable error (the pool self-heals via quarantine + respawn).	Constrained containers (cgroup CPU limits) or CI runners with explicit quotas. To narrow down a worker crash set `1` for a single-worker pool — not `0`.
`GITNEXUS_PARSE_CHUNK_CONCURRENCY`	`2`	Number of chunks whose file contents may be read into memory in parallel while the pool dispatches the current chunk. Worker dispatch itself stays serial.	Repos large enough to chunk (multi-MB total source) where disk I/O is a measurable fraction of analyze wall-clock.
`GITNEXUS_VERBOSE`	unset	When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`.	Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput.
`GITNEXUS_AUTH_TOKEN`	unset	Bearer token required when `eval-server` binds beyond loopback. May also be read from `.env.local` or `.env`; shell values take precedence.	Exposing the evaluation HTTP tools to a container, VM, or LAN.
`GITNEXUS_PROFILE_DEFERRED`	unset	When `1`, emits `[deferred-profile]` timing/progress logs for the post-chunk deferred resolution band (imports → heritage → buildHeritageMap → legacy call resolution). Implied by `GITNEXUS_VERBOSE`.	Diagnosing analyze stalls in "Resolving calls (all chunks)" on large Java/Kotlin repos (issue #1741) without the full verbose ingestion noise.
`GITNEXUS_PROFILE_DEFERRED_SLOW_MS`	`3000` (verbose) / `5000`	Per-file threshold in ms above which `processCallsFromExtracted` emits a `slow file …` log line. Parsed via `Number()`: accepts integers (`5000`), scientific notation (`2.5e3`), decimals (`.5`), and hex (`0x10`). Non-finite or non-positive values fall back to the default.	Hunting a few outlier files dominating the deferred call-resolution stage; lower to surface more, raise to focus only on the worst.
`PROF_LBUG_LOAD`	unset	When `1`, emits one `[lbug-load prof]` summary line per `loadGraphToLbug` call breaking the graph-DB persistence wall into stages (`csv-emit` / `copy-nodes` / `copy-rels` / `fallback` / `total`) plus node & edge counts. Zero-cost when unset.	Attributing large-repo analyze wall time across CSV generation vs. LadybugDB `COPY` (issue #2203) — the analyze "emit" timing is the scope-resolution bucket, not this DB-write path.
`GITNEXUS_MAX_FILE_SIZE`	`512` (KB)	Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`.	Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed.
`GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS`	`30000`	Worker idle timeout in milliseconds before retry/fallback. Equivalent to `--worker-timeout <seconds>` × 1000.	Slow-parsing files (large minified JS, deeply-nested TS types) that legitimately need more than 30s.
`GITNEXUS_WORKER_READY_TIMEOUT_MS`	`5000`	Startup budget in milliseconds for a parse worker to load its grammar bindings and report `{type:'ready'}`. Slots that miss it are treated as startup crashes.	Slow or heavily loaded hosts where a full pool cold-starting concurrently needs more than 5s, and analyze aborts with "did not report ready within 5000ms".
`GITNEXUS_FTS_STEMMER`	`porter`	Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` for matching repository comments. Re-run `gitnexus analyze --repair-fts` after changing it.	Keyword search quality is poor for non-English comments or identifiers under English stemming.
`GITNEXUS_WAL_CHECKPOINT_THRESHOLD`	`67108864` (64 MiB)	LadybugDB WAL auto-checkpoint threshold in bytes. Equivalent to `--wal-checkpoint-threshold <bytes>`. `-1` keeps LadybugDB's stock threshold (~16 MiB). Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.	You need a larger or smaller WAL auto-checkpoint threshold for your analyze workload.
`GITNEXUS_LBUG_BUFFER_POOL_SIZE`	min(2 GiB, 80% RAM)	LadybugDB buffer-pool ceiling in bytes for every GitNexus database (analyze, MCP server, serve, group bridges). `0` restores LadybugDB's native unbounded default of 80% of system RAM; invalid values warn and fall back to the default (#2557). During `analyze` the pool is right-sized to the graph, scaled on non-4 KiB-page hosts by the page-size granule ratio up to min(2 GiB × pageSize/4 KiB, 80% RAM) (#2631); this env var overrides all of that as an absolute value.	A long-lived `gitnexus mcp` or a big incremental `analyze` uses too much memory, or a huge repo's working set genuinely needs a pool larger than 2 GiB.
`GITNEXUS_LBUG_MAX_DB_SIZE`	`17179869184` (16 GiB)	Maximum size in bytes of a single LadybugDB database file — an mmap/disk-address-space ceiling, not a memory limit (it does not constrain the buffer pool). Invalid values silently fall back to the default.	Indexing a genuinely huge monorepo whose on-disk graph index approaches 16 GiB.
`GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES`	`8388608` (8 MB)	Per-job byte budget the pool will send to a worker in one `postMessage`.	Very large individual files; mostly diagnostic — bumping past 8 MB risks structured-clone memory pressure.
`GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`	`3`	Max replacement spawns per worker slot before the slot is dropped from the active rotation. Bounds respawn loops on a chronically-crashing slot.	Hosts where a flaky worker should retry more (raise) or fail-fast (lower) before the slot is dropped.
`GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`	`5 × subBatchTimeoutMs`	Total retry wall-time budget per job before quarantining. Combined with `timeoutBackoffFactor`, prevents exponentially-growing retries from stalling for hours.	Slow files that legitimately need long total retry windows; lower to fail-fast on stalls.
`GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`	`max(3, poolSize)`	Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, every subsequent dispatch rejects until a fresh pool is created.	Hosts where a SIGSEGV-prone native grammar should trip the breaker sooner; CI runners that should fail loudly.
`GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS`	`30000`	Max wait at pool shutdown for a retired worker still inside native code. The worker is terminated at its next JS-safe point instead of mid-native-call (which aborts the whole process with `Napi::Error`, #2432); on expiry it is left running, unref'd, and terminated when it surfaces.	Shutdown latency matters more than draining a wedged worker (lower), or a legitimately-slow native grammar needs longer to surface (raise).
`GITNEXUS_CPP_CAPTURE_BUDGET_MS`	`20000`	Per-file wall-clock budget for C++ capture extraction. On breach the file keeps the captures accumulated so far and logs a warning — the worker returns to JS instead of stalling in native-heavy loops (#2432). `0` expires immediately.	Pathological generated C++ that still exceeds the budget after the indexed lookups; raise for completeness, lower to fail-fast.
`GITNEXUS_CHUNK_BYTE_BUDGET`	`2097152` (2 MB)	Chunk boundary used for cache-key composition and dispatch. Smaller = finer-grained cache hits but more dispatch overhead.	Tuning incremental-analyze cache behavior on monorepos.
`GITNEXUS_NO_GITIGNORE`	unset	When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored.	Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup).
`GITNEXUS_SKIP_OPTIONAL_GRAMMARS`	unset	When `=1` strictly, skips the vendored grammar materialize for `tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift`, and `tree-sitter-kotlin` at install time (and the Dart/Proto source builds). Those four won't be parsed; the install still succeeds.	Installing on a host without a C++ toolchain or where the vendored prebuilds don't match; willing to skip Dart/Proto/Swift/Kotlin parsing.
`GITNEXUS_MCP_READ_ONLY`	unset	Set to `1` to expose only proven single-repository read tools and resources; `0` disables the policy and any other value fails startup.	The MCP server runs in an environment where graph mutation, raw Cypher, and cross-repository group routing must be unavailable.
`GITNEXUS_MCP_ALLOWED_REPOS`	unset	Comma-separated allowlist of canonical indexed repository names or absolute paths. Invalid, ambiguous, or blank entries fail startup.	One MCP process must expose only a bounded subset of the repositories in the global registry.
`GITNEXUS_MCP_DEFAULT_REPO`	unset	Canonical indexed repository name or absolute path used when a tool or resource omits its repository. Must belong to the allowlist when one is set.	Several repositories are available but unqualified MCP calls should resolve deterministically.
`GITNEXUS_MCP_DEFAULT_MAX_TOKENS`	unset	Default positive-integer response budget for MCP `query`, `context`, and `impact`, estimated at four UTF-8 bytes per token. Explicit `maxTokens` wins.	Long MCP responses consume too much model context and callers cannot reliably add a per-request budget.

gitnexus uninstall

gitnexus uninstall reverses gitnexus setup — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified by bundled gitnexus skill name (e.g. gitnexus-cli/), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass --force to apply. Per-repo indexes (gitnexus clean --all) and the global npm package (npm uninstall -g gitnexus) are left for you to remove.

Publishing to understand-quickly (opt-in)

looptech-ai/understand-quickly is a public registry of code-knowledge graphs that lists gitnexus@1 as a first-class format. After registering your repo once (npx @understand-quickly/cli add or the wizard), gitnexus publish fires a single repository_dispatch event so the registry resyncs your entry on demand instead of waiting for the nightly job.

It is opt-in and a no-op without UNDERSTAND_QUICKLY_TOKEN — a fine-grained GitHub PAT with Repository dispatches: write on the registry repo. Nothing else happens; no graph file is uploaded. See the protocol spec for the full contract.

How It Works

GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:

Structure — walks the file tree and maps folder/file relationships
Parsing — extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
Resolution — resolves imports, function calls, heritage, constructor inference, and self/this receiver types across files with language-aware logic
Clustering — groups related symbols into functional communities
Processes — traces execution flows from entry points through call chains
Search — builds hybrid search indexes for fast retrieval

Supported Languages

Language	Imports	Named Bindings	Exports	Heritage	Type Annotations	Constructor Inference	Config	Frameworks	Entry Points
TypeScript	✓	✓	✓	✓	✓	✓	✓	✓	✓
JavaScript	✓	✓	✓	✓	—	✓	✓	✓	✓
Python	✓	✓	✓	✓	✓	✓	✓	✓	✓
Java	✓	✓	✓	✓	✓	✓	—	✓	✓
Kotlin	✓	✓	✓	✓	✓	✓	—	✓	✓
C#	✓	✓	✓	✓	✓	✓	✓	✓	✓
Go	✓	—	✓	✓	✓	✓	✓	✓	✓
Rust	✓	✓	✓	✓	✓	✓	—	✓	✓
PHP	✓	✓	✓	—	✓	✓	✓	✓	✓
Ruby	✓	—	✓	✓	—	✓	—	✓	✓
Swift	—	—	✓	✓	✓	✓	✓	✓	✓
C	—	—	✓	—	✓	✓	—	✓	✓
C++	—	—	✓	✓	✓	✓	—	✓	✓
Dart	✓	—	✓	✓	✓	✓	—	✓	✓

Imports — cross-file import resolution · Named Bindings — import { X as Y } / re-export tracking · Exports — public/exported symbol detection · Heritage — class inheritance, interfaces, mixins · Type Annotations — explicit type extraction for receiver resolution · Constructor Inference — infer receiver type from constructor calls (self/this resolution included for all languages) · Config — language toolchain config parsing (tsconfig, go.mod, etc.) · Frameworks — AST-based framework pattern detection · Entry Points — entry point scoring heuristics

Control flow (CFG, opt-in --pdg) — per-function control-flow graphs (BasicBlock nodes + CFG edges) feeding the PDG/taint substrate, currently TypeScript & JavaScript (#2081 M1); other languages planned. Off by default.

Multi-Repo Architecture

GitNexus uses a global registry so one MCP server can serve multiple indexed repos. No per-project MCP config needed — set it up once and it works everywhere.

Each gitnexus analyze stores the index in .gitnexus/ inside the repo (portable, gitignored) and registers a pointer in ~/.gitnexus/registry.json. When an AI agent starts, the MCP server reads the registry and can serve any indexed repo. LadybugDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). If only one repo is indexed, the repo parameter is optional on all tools — agents don't need to change anything.

Architecture diagram

flowchart TD
    subgraph CLI [CLI Commands]
        Setup["gitnexus setup"]
        Analyze["gitnexus analyze"]
        Clean["gitnexus clean"]
        List["gitnexus list"]
    end

    subgraph Registry ["~/.gitnexus/"]
        RegFile["registry.json"]
    end

    subgraph Repos [Project Repos]
        RepoA[".gitnexus/ in repo A"]
        RepoB[".gitnexus/ in repo B"]
    end

    subgraph MCP [MCP Server]
        Server["server.ts"]
        Backend["LocalBackend"]
        Pool["Connection Pool"]
        ConnA["LadybugDB conn A"]
        ConnB["LadybugDB conn B"]
    end

    Setup -->|"writes global MCP config"| CursorConfig["~/.cursor/mcp.json"]
    Analyze -->|"registers repo"| RegFile
    Analyze -->|"stores index"| RepoA
    Clean -->|"unregisters repo"| RegFile
    List -->|"reads"| RegFile
    Server -->|"reads registry"| RegFile
    Server --> Backend
    Backend --> Pool
    Pool -->|"lazy open"| ConnA
    Pool -->|"lazy open"| ConnB
    ConnA -->|"queries"| RepoA
    ConnB -->|"queries"| RepoB

Tool Examples

Impact Analysis

impact({target: "UserService", direction: "upstream", minConfidence: 0.8})

TARGET: Class UserService (src/services/user.ts)

UPSTREAM (what depends on this):
  Depth 1 (WILL BREAK):
    handleLogin [CALLS 90%] -> src/api/auth.ts:45
    handleRegister [CALLS 90%] -> src/api/auth.ts:78
    UserController [CALLS 85%] -> src/controllers/user.ts:12
  Depth 2 (LIKELY AFFECTED):
    authRouter [IMPORTS] -> src/routes/auth.ts

Options: maxDepth, minConfidence, relationTypes (CALLS, IMPORTS, EXTENDS, IMPLEMENTS), includeTests, limit (max symbols per depth, default 100), offset (pagination start per depth), summaryOnly (counts and risk only, omits symbol list)

Disambiguation — when several symbols share the target name, impact returns a ranked ambiguous candidate list instead of guessing. Narrow it with target_uid (exact, zero-ambiguity), file_path, or kind (Function, Class, Method, …). From the CLI these are --uid, --file, and --kind, matching gitnexus context:

gitnexus impact get_embeddings                       # → ambiguous: lists ranked candidates
gitnexus impact get_embeddings --file src/embed.py   # → resolves to the one in that file
gitnexus impact get_embeddings --uid "Function:src/embed.py:get_embeddings"  # exact

More examples: search · context · detect_changes · rename · Cypher

Process-Grouped Search

query({search_query: "authentication middleware"})

processes:
  - summary: "LoginFlow"
    priority: 0.042
    symbol_count: 4
    process_type: cross_community
    step_count: 7

process_symbols:
  - name: validateUser
    type: Function
    filePath: src/auth/validate.ts
    process_id: proc_login
    step_index: 2

definitions:
  - name: AuthConfig
    type: Interface
    filePath: src/types/auth.ts

Context (360-degree Symbol View)

context({name: "validateUser"})

symbol:
  uid: "Function:validateUser"
  kind: Function
  filePath: src/auth/validate.ts
  startLine: 15

incoming:
  calls: [handleLogin, handleRegister, UserController]
  imports: [authRouter]

outgoing:
  calls: [checkPassword, createSession]

processes:
  - name: LoginFlow (step 2/7)
  - name: RegistrationFlow (step 3/5)

Detect Changes (Pre-Commit)

detect_changes({scope: "all"})

summary:
  changed_count: 12
  affected_count: 3
  changed_files: 4
  risk_level: medium

changed_symbols: [validateUser, AuthService, ...]
affected_processes: [LoginFlow, RegistrationFlow, ...]

Rename (Multi-File)

rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})

status: success
files_affected: 5
total_edits: 8
graph_edits: 6     (high confidence)
text_search_edits: 2  (review carefully)
changes: [...]

Cypher Queries

-- Find what calls auth functions with high confidence
MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn)
MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn)
WHERE r.confidence > 0.8
RETURN caller.name, fn.name, r.confidence
ORDER BY r.confidence DESC

Wiki Generation

Generate LLM-powered documentation from your knowledge graph:

# Requires an LLM API key (OPENAI_API_KEY, etc.)
gitnexus wiki

# Use a custom model or provider (default model: minimax/minimax-m2.5)
gitnexus wiki --model gpt-4o
gitnexus wiki --base-url https://api.anthropic.com/v1

# Force full regeneration
gitnexus wiki --force

# Increase the timeout or retries for large codebases or slow LLM providers
gitnexus wiki --timeout <seconds>  # LLM request timeout in seconds (default: disabled)
gitnexus wiki --retries <n>        # Max LLM retry attempts per request (default: 3)

# Allow a specific LAN/self-hosted HTTP LLM host (HTTPS is preferred for remote endpoints)
gitnexus wiki --base-url http://llama-box.local:8080/v1 --allow-insecure-connection llama-box.local
# Or set a comma-separated host allowlist:
GITNEXUS_ALLOW_INSECURE_CONNECTION=llama-box.local,192.168.1.23

# Change the output language
gitnexus wiki --lang <lang>  # e.g. english, chinese, spanish, japanese

For safety, http:// LLM base URLs are allowed by default only for loopback hosts (localhost, 127.0.0.1, ::1). --allow-insecure-connection and GITNEXUS_ALLOW_INSECURE_CONNECTION accept exact hostnames or IP addresses only; do not include schemes, ports, paths, credentials, or wildcards.

The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.

Web UI (browser-based)

A client-side graph explorer and AI chat — your code never leaves your machine.

Try it now: gitnexus.vercel.app — run npx gitnexus@latest serve locally and the page auto-connects to your local backend.

The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, LadybugDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos.

Local Backend Mode: run gitnexus serve and open the web UI — it auto-detects the server and shows all your indexed repos, with full AI chat support. No re-upload, no re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.

Run the frontend locally

git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus/gitnexus-shared && npm install && npm run build
cd ../gitnexus-web && npm install
npm run dev
# Then in another terminal, start the backend the frontend connects to:
npx gitnexus@latest serve

Docker

docker compose up -d

This starts the server on http://localhost:4747 and the web UI on http://localhost:4173. The UI auto-detects the server because the browser runs on the host and reaches the container via the mapped port.

The official setup ships two signed images, published identically to GitHub Container Registry (GHCR) and Docker Hub — same build, same digest, same Cosign signature:

Purpose	GHCR (default in `docker-compose.yaml`)	Docker Hub mirror
CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer)	`ghcr.io/abhigyanpatwari/gitnexus:latest`	`akonlabs/gitnexus:latest`
Static web UI (port `4173`)	`ghcr.io/abhigyanpatwari/gitnexus-web:latest`	`akonlabs/gitnexus-web:latest`

A named volume (gitnexus-data) persists the global registry, indexes, and cloned repos at /data/gitnexus inside the server container. To make repos on your host machine indexable, set WORKSPACE_DIR before bringing the stack up:

WORKSPACE_DIR=$HOME/code docker compose up -d
# Inside the server container the directory is mounted read-only at /workspace.
docker compose exec gitnexus-server gitnexus index /workspace/my-repo

Heads-up — image rename. Earlier releases published the web UI under ghcr.io/abhigyanpatwari/gitnexus. That slug now hosts the CLI/server image and the UI moved to ghcr.io/abhigyanpatwari/gitnexus-web. Previous tags remain pullable, but new versions are only published under the new slugs — update your docker run / compose files (or just adopt the bundled compose).

Direct docker run & env file

# Server
docker run --rm -d \
  --name gitnexus-server \
  -p 4747:4747 \
  -v gitnexus-data:/data/gitnexus \
  ghcr.io/abhigyanpatwari/gitnexus:latest

# Web UI
docker run --rm -d \
  --name gitnexus-web \
  -p 4173:4173 \
  ghcr.io/abhigyanpatwari/gitnexus-web:latest

Optional env file (override image tags, container names, ports, workspace dir):

cp .env.example .env
docker compose --env-file .env up -d

Files:

Dockerfile.web — builds gitnexus-shared and gitnexus-web, then serves the production frontend.
Dockerfile.cli — builds the CLI/server (with its native deps) and runs gitnexus serve --host 0.0.0.0.
docker-compose.yaml — starts both signed images side by side.
.env.example — overrides for image names, container names, ports, and the workspace mount.

Versioning & supply-chain protection (Cosign signatures, provenance, Kubernetes admission policy)

The Docker images are version-locked to the npm package:

Stable images are only published from vX.Y.Z git tags (via docker.yml triggered directly by the tag push), and the workflow refuses to build unless the tag exactly matches gitnexus/package.json's version. So ghcr.io/abhigyanpatwari/gitnexus:1.6.2 (and its Docker Hub mirror akonlabs/gitnexus:1.6.2) is byte-for-byte the same release as npm install gitnexus@1.6.2 — no drift, no floating builds from main. Both registries receive the same digest from a single build step, so you can pull from either and the signature verifies identically.
Release-candidate images (e.g. :1.7.0-rc.1) are published alongside each RC npm release. They are built by publish.yml calling docker.yml as a reusable workflow after the RC tag is created and pushed.
:latest is auto-promoted only from non-prerelease tags by the Docker metadata action, so it always points at a real, npm-published version.

Both images are signed with Cosign keyless signing using the workflow's GitHub OIDC identity, and shipped with build provenance and SBOM attestations. This is your protection against supply-chain attacks: even if an attacker republishes a same-named image elsewhere (or somehow pushes to a typo-squatted registry), they cannot forge a Cosign signature tied to abhigyanpatwari/GitNexus's docker.yml. Always verify before pulling into sensitive environments.

Stable releases — signed from the v* tag ref:

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# Same signature verifies the Docker Hub mirror (identical digest):
cosign verify docker.io/akonlabs/gitnexus:1.6.2 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The regex pins the certificate identity to this repo's docker.yml workflow run from a v* tag — rejecting unsigned images, images signed by other workflows, and images signed from unprotected refs. It is identical for both registries because both sets of tags were signed at the same digest in one workflow run.

Release candidates — signed from refs/heads/main (the caller's ref when publish.yml invokes docker.yml as a reusable workflow):

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
  --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

You can also inspect the build provenance and SBOM:

cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
  --predicate-type https://slsa.dev/provenance/v1

Kubernetes: enforce signatures at admission. Ship the bundled ClusterImagePolicy so the Sigstore policy-controller rejects any GitNexus pod whose image is not signed by this repo's docker.yml running from a vX.Y.Z tag — the same identity the cosign verify snippet above pins.

# 1. Install the controller (one-time, cluster-wide)
helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
helm install policy-controller -n cosign-system --create-namespace \
  sigstore/policy-controller

# 2. Opt your namespace in
kubectl label namespace <your-ns> policy.sigstore.dev/include=true

# 3. Apply the policy
kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml

After this, attempting to deploy an unsigned image — or one signed by anything other than abhigyanpatwari/GitNexus's docker.yml at a v* tag — fails the admission webhook before a pod is ever created. This turns the verifiable signature into an enforced policy, which is the supply-chain control most clusters actually need.

Enterprise

GitNexus is available as an enterprise offering — fully managed SaaS or self-hosted deployment. Commercial use of the OSS version is also available with proper licensing.

Enterprise includes:

PR Review — automated blast radius analysis on pull requests
Auto-updating Code Wiki — always up-to-date documentation (Code Wiki is also available in OSS)
Auto-reindexing — knowledge graph stays fresh automatically
Multi-repo support — unified graph across repositories
OCaml support — additional language coverage
Priority feature/language support — request new languages or features

Upcoming: auto regression forensics · end-to-end test generation

👉 Learn more at akonlabs.com — for commercial licensing or enterprise inquiries, ping us on Discord or email founders@akonlabs.com

Community Integrations

Built by the community — not officially maintained, but worth checking out.

Project	Author	Description
pi-gitnexus	@tintinweb	GitNexus plugin for pi — `pi install npm:pi-gitnexus`
gitnexus-stable-ops	@ShunsukeHayashi	Stable ops & deployment workflows (Miyabi ecosystem)
KiloCode MCP workflow	@oktanishq	Guide to connect GitNexus MCP to Kilo Code and verify tools.

Have a project built on GitNexus? Open a PR to add it here!

Roadmap

Actively building:

LLM Cluster Enrichment — semantic cluster names via LLM API
AST Decorator Detection — parse @Controller, @Get, etc.
Incremental Indexing — only re-index changed files

Recently completed:

Constructor-Inferred Type Resolution, self/this Receiver Mapping
Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
Process-Grouped Search, 360-Degree Context, Claude Code Hooks
Multi-Repo MCP, Zero-Config Setup, 14 Language Support
Community Detection, Process Detection, Confidence Scoring
Hybrid Search, Vector Index

Development

ARCHITECTURE.md — packages, index → graph → MCP flow, where to change code
RUNBOOK.md — analyze, embeddings, stale index, MCP recovery, CI snippets
GUARDRAILS.md — safety rules and operational "Signs" for contributors and agents
CONTRIBUTING.md — license, setup, commits, and pull requests
TESTING.md — test commands for gitnexus and gitnexus-web

Tech Stack

Layer	CLI	Web
Runtime	Node.js (native)	Browser (WASM)
Parsing	Tree-sitter native bindings	Tree-sitter WASM
Database	LadybugDB native	LadybugDB WASM
Embeddings	HuggingFace transformers.js (GPU/CPU)	transformers.js (WebGPU/WASM)
Search	BM25 + semantic + RRF	BM25 + semantic + RRF
Agent Interface	MCP (stdio)	LangChain ReAct agent
Visualization	—	Sigma.js + Graphology (WebGL)
Frontend	—	React 18, TypeScript, Vite, Tailwind v4
Clustering	Graphology	Graphology
Concurrency	Worker threads + async	Web Workers + Comlink

Security & Privacy

CLI: everything runs locally on your machine. No network calls. Index stored in .gitnexus/ (gitignored). Global registry at ~/.gitnexus/ stores only paths and metadata.
Web: everything runs in your browser. No code uploaded to any server. API keys stored in localStorage only.
Open source — audit the code yourself.

Star History

Acknowledgments

Tree-sitter — AST parsing
LadybugDB — embedded graph database with vector support (formerly KuzuDB)
Sigma.js — WebGL graph rendering
transformers.js — browser ML
Graphology — graph data structures
MCP — Model Context Protocol

README.md Unescape Escape