Related Pages

Related topics: System Architecture & Indexing Pipeline, AI Agent Integration & MCP Tools, Operations, Troubleshooting & Extensibility

Overview & Getting Started

What is GitNexus

GitNexus is a graph-powered code intelligence tool for AI agents. It precomputes every dependency, call chain, and relationship in a codebase into a queryable knowledge graph, then exposes that graph through both an MCP (Model Context Protocol) interface and a CLI. The goal is to give AI coding tools structural awareness of a repository so that edits to one function account for the dozens of other functions that depend on it. Source: README.md:1-15.

The system is published as a single npm package, gitnexus, distributed under the PolyForm Noncommercial license. Source: package.json:1-12. The package ships a bin entry that exposes the gitnexus command, Claude Code / Cursor hook scripts, agent skill files, and a built-in web UI. Source: package.json:21-44. GitNexus targets AI agents that already speak MCP — Cursor, Claude Code, Codex, Windsurf, Cline, OpenCode, Antigravity — plus any generic MCP-compatible client. Source: README.md:1-15.

How It Works

Indexing runs as a typed, multi-phase pipeline that turns a directory tree into a fully linked knowledge graph. The phases are defined as a discriminated union in shared code: idle, extracting, structure, parsing, imports, calls, heritage, scopeResolution, communities, processes, enriching, complete, error. Source: gitnexus-shared/src/pipeline.ts:1-15.

Conceptually the pipeline executes in this order: Structure walks the file tree and creates Folder / File / Module nodes; Parsing extracts functions, classes, methods, and interfaces using Tree-sitter ASTs; Imports resolves cross-file references; Calls links call sites to their resolved callees; Heritage connects EXTENDS / IMPLEMENTS edges; Scope Resolution → Communities → Processes binds local symbols, clusters them into functional communities, and traces execution flows from entry points. The shared scope-resolution finalize algorithm runs as an SCC-aware fixpoint bounded by edge count, so cyclic imports finalize without hanging. Source: gitnexus-shared/src/scope-resolution/finalize-algorithm.ts:1-35.

The resulting graph is persisted in LadybugDB, an embedded graph database. The schema is a single source of truth shared between the CLI and the web UI: the canonical NODE_TABLES list (File, Folder, Function, Class, Method, Process, Community, BasicBlock, …) and REL_TYPES (CONTAINS, DEFINES, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, METHOD_OVERRIDES, …) live in gitnexus-shared/src/lbug/schema-constants.ts. Source: gitnexus-shared/src/lbug/schema-constants.ts:1-50.

Language support is exhaustive and typed. The EXTENSION_MAP is a Record<SupportedLanguages, readonly string[]> so adding a new language forces a TypeScript compile error until both the enum and the extensions are updated. Source: gitnexus-shared/src/language-detection.ts:1-60. Languages are classified production or experimental; production languages (TypeScript, Python, Go, Rust, Java, C++, C#, Ruby, PHP, Kotlin, Swift, Dart) gate Ring 4 retirement, while Vue and Cobol are still experimental. Source: gitnexus-shared/src/scope-resolution/language-classification.ts:1-25.

flowchart LR
  A[Source Tree] --> B[Structure]
  B --> C[Parsing: Tree-sitter]
  C --> D[Imports Resolution]
  D --> E[Calls Resolution]
  E --> F[Heritage + Scope]
  F --> G[Communities]
  G --> H[Processes]
  H --> I[(LadybugDB Graph)]
  I --> J[MCP Server /api/mcp]
  I --> K[CLI Commands]
  I --> L[Web UI]

Quick Start

Requirements. Node.js ≥ 18 and a Git repository. Source: README.md:1-180.

One-shot install and index. From a repo root:

npx gitnexus analyze

This single command indexes the codebase, installs agent skills, registers Claude Code hooks, and writes AGENTS.md / CLAUDE.md context files into the working repo. Source: README.md:1-40.

Alternative install paths. The same command runs against a release candidate for early testing:

npm install -g gitnexus@rc
npx gitnexus@rc analyze

Release candidates publish under the rc dist-tag whenever a non-documentation change merges into main. The 1.6.8 cycle shipped rc builds 44 through 52; the 1.6.9 cycle is currently at rc.9. Source: package.json:1-15, community release evidence.

Pinning for restricted networks. On locked-down environments (e.g., Debian with only an npm mirror reachable) the native bindings from @ladybugdb/core may be unavailable, which surfaces as install-time warnings. The README's recommended form is pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus .... Source: README.md:1-60, community issue #2184.

Uninstalling. There is no first-class gitnexus uninstall yet. Community issue #112 documents that gitnexus clean removes the .gitnexus/ index but leaves behind AGENTS.md, CLAUDE.md, hooks, and the global registry entry.

MCP Tools, CLI, and Interfaces

The MCP server is mounted by the web-UI server at /api/mcp and streams JSON-RPC over HTTP via createStreamableHttpHandler. Source: gitnexus/src/server/mcp-http.ts:1-30. The browser upload path (POST /api/analyze/upload) reuses the same job/worker machinery as a git clone but never returns a server path to the client. Source: gitnexus/src/server/analyze-upload.ts:1-30.

The standard tool surface exposed to agents is:

Source: README.md:1-150.

The same capabilities are available without an MCP daemon through the CLI: gitnexus query, gitnexus context <symbol>, gitnexus impact <symbol>, gitnexus detect-changes, gitnexus cypher "<query>". Direct graph queries use the same code paths as the MCP server, so behavior stays consistent. Source: README.md:1-100.

For multi-repo or monorepo work, gitnexus group create | add | remove | list | sync | contracts builds a cross-repository service map. The web UI (gitnexus-web) renders the graph with node sizes, colors, and visual hierarchy defined in a single constants module — e.g., Project is rendered largest (size 20) and Import smallest (size 1.5), reflecting its role as a leaf edge. Source: gitnexus-web/src/lib/constants.ts:1-50.

An opt-in integration publishes an index entry to the looptech-ai/understand-quickly registry through a single GitHub repository_dispatch event, gated by the UNDERSTAND_QUICKLY_TOKEN environment variable. Source: gitnexus-shared/src/integrations/understand-quickly.ts:1-30.

Common Failure Modes

Recurring issues from the community to know about up front:

• C++ symbol linking hangs. Long-running C/C++ indexing can appear stuck during the linking phase (issues #1973, #2243, 1.6.7).
• FTS unavailable in restricted networks. @ladybugdb/core needs native build support; if disabled, full-text search features silently degrade (issue #2184).
• Wiki index not initialized. Running gitnexus wiki --lang chinese (or any wiki command without a prior index) raises LadybugDB not initialized for repo "__wiki__" (issue #2225).

See Also

• Indexing Pipeline (phases, progress reporting)
• Knowledge Graph Schema (node tables, relations)
• MCP Server Reference (tools, resources, transports)
• CLI Command Reference
• Multi-Repo Groups (cross-repository service tracking)
• Agent Skills (installed by analyze and setup)

Related Pages

Related topics: Overview & Getting Started, AI Agent Integration & MCP Tools, Operations, Troubleshooting & Extensibility

System Architecture & Indexing Pipeline

GitNexus is a graph-powered code intelligence system that turns any git repository into a queryable LadybugDB knowledge graph, exposing it to AI agents via the Model Context Protocol (MCP). The system is delivered as a single npm package (gitnexus) and is composed of three cooperating sub-projects: the Node CLI (gitnexus/), the shared runtime types (gitnexus-shared/), and the web UI (gitnexus-web/). All three converge on a single canonical schema so that an index built by the CLI can be opened by the browser.

High-Level Architecture

flowchart LR
    User[Developer + AI Agent] -->|analyze / serve| CLI[gitnexus CLI]
    User -->|browser folder| Web[gitnexus-web]
    CLI -->|writes| DB[(.gitnexus/ LadybugDB)]
    Web -->|reads| DB
    CLI -->|mounts| MCP[/api/mcp]
    MCP --> Agent[Cursor / Claude / Codex / Windsurf]
    Web --> WASM[LadybugDB WASM]
    Shared[gitnexus-shared: pipeline + scope types] -.-> CLI
    Shared -.-> Web
    TreeSitter[tree-sitter grammars] --> CLI
    TreeSitter --> Web

The package's package.json declares a single bin entry (gitnexus → dist/cli/index.js) and ships dist, hooks, scripts, skills, vendor, and web artifacts, meaning one install yields the CLI, agent skill files, and the in-browser UI simultaneously. Source: gitnexus/package.json.

Indexing Pipeline Phases

The PipelinePhase enum in gitnexus-shared/src/pipeline.ts is the canonical phase machine shared between CLI progress bars and web progress UI:

idle → extracting → structure → parsing → imports
     → calls → heritage → scopeResolution → communities
     → processes → enriching → complete | error

Source: gitnexus-shared/src/pipeline.ts.

Language support is gated by SupportedLanguages and the exhaustive EXTENSION_MAP in gitnexus-shared/src/language-detection.ts, which uses a TypeScript Record keyed by the enum so that adding a new language without registering extensions becomes a compile-time error. The same file maps file extensions to Prism syntax identifiers for the web viewer. Source: gitnexus-shared/src/language-detection.ts.

Scope Resolution and the Semantic Model

Phases 4–7 (imports through scope resolution) are the heart of the linker. The shared finalize algorithm is SCC-aware: it runs Tarjan's algorithm over the file-level import graph, processes SCCs in reverse-topological order, and inside each SCC runs a bounded fixpoint cap at N = |edges in SCC|. This guarantees that cyclic imports finalize without hanging and that malformed inputs are bounded by the cap rather than the global edge count. The algorithm is pure logic — it accepts ParsedImport[] and SymbolDefinition[] plus caller-supplied hooks (resolveImportTarget, expandsWildcardTo, mergeBindings) so language-specific rules (wildcards, re-exports, binding precedence) live in per-language providers, not in the shared code. Source: gitnexus-shared/src/scope-resolution/finalize-algorithm.ts.

The Scope interface encodes a deterministic, interned ScopeId of the shape scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}, stable across reparses of identical source. TypeRef deliberately defers generics (a typeArgs field is reserved for V2) so that V1 stays tractable while preserving correctness for aliases, re-exports, and nested modules. Source: gitnexus-shared/src/scope-resolution/types.ts.

A separate MethodDispatchIndex (mroByOwnerDefId, implsByInterfaceDefId, optional extendsOnlyMroByOwnerDefId) feeds the MRO fast path and the super-branch dispatch in receiver-bound-calls. The extendsOnly view is populated only for languages with mixin-like semantics (e.g. PHP traits) so callers can fall back to the standard MRO otherwise. Source: gitnexus-shared/src/scope-resolution/method-dispatch-index.ts.

Storage Schema and Query Surface

The CLI writes to a LadybugDB database inside .gitnexus/. The single source of truth for what nodes and edges exist is NODE_TABLES and REL_TYPES in gitnexus-shared/src/lbug/schema-constants.ts. Node tables include the structural spine (File, Folder, Module, Namespace, Section), the code spine (Function, Class, Interface, Method, Struct, Enum, Trait, Impl, TypeAlias, Record, Delegate, Annotation, Constructor, Template, Macro, Typedef, Union, Const, Static, Variable, Property), metadata (Community, Process, Tool), and a BasicBlock substrate reserved for the future taint/PDG work tracked in issue #2080. All relationships flow through a single CodeRelation table whose REL_TYPES array lists every legal edge kind (e.g. CONTAINS, DEFINES, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, METHOD_OVERRIDES). Source: gitnexus-shared/src/lbug/schema-constants.ts. The full DDL remains duplicated in each package because the CLI uses native LadybugDB while the web loads WASM.

The MCP server is mounted at /api/mcp by mountMCPEndpoints, which wires createStreamableHttpHandler onto an existing Express app and returns a cleanup callback for graceful shutdown. Source: gitnexus/src/server/mcp-http.ts.

Browser-Side Ingestion Path

The web UI offers an alternate ingestion route: a webkitdirectory upload. To keep payloads small, filterRepoFiles in gitnexus-web/src/lib/upload-filter.ts drops VCS metadata (.git, .hg, .svn), dependency dirs (node_modules, vendor, .venv, __pycache__), build outputs (target, dist, build, out, .next, .nuxt, .cache, coverage), and IDE / GitNexus state (.idea, .gitnexus) before a 25 MB per-file cap is enforced. The server handler analyze-upload.ts then ingests the multipart payload into a sandbox, promotes it to a persistent app-controlled directory, and re-uses the same createJob + worker launcher machinery as a git-clone analysis path. The handler is factored as a dependency-injected function (createJob, launch, markFailed) so the job layer can be mocked in unit tests. Source: gitnexus-web/src/lib/upload-filter.ts, gitnexus/src/server/analyze-upload.ts.

Known Failure Modes (Community-Reported)

• C++ symbol linker stalls — Issue #2243 / #1973 reports the parsing/imports phases hanging on C++ codebases. Because the finalize algorithm caps iterations per SCC at N = |edges in SCC|, large cyclic C++ header graphs can spend the full cap repeatedly without converging. Workarounds live in the per-language C++ provider hook, not in the shared algorithm. Source: scope-resolution/finalize-algorithm.ts.
• Offline install + FTS — Issue #2184 reports that on Debian mirrors without general network, the optional FTS native binding fails to fetch. FTS is a separate optional component, not part of the canonical pipeline phases.
• LadybugDB not initialized for repo "__wiki__" — Issue #2225 shows the gitnexus wiki --lang chinese command calling into the LadybugDB layer before initLbug runs against the special __wiki__ synthetic repo, producing an uninitialized-database error that is independent of the --lang flag.
• Unconditional writes to CLAUDE.md / AGENTS.md — Issue #1265 reports that gitnexus analyze always edits four surfaces in the working repo. There is currently no opt-out flag, env var, or config sentinel — teams that own those files cannot use analyze without losing their content.
• Missing uninstall — Issue #112 notes that gitnexus clean only removes the .gitnexus/ index and unregisters the global registry; artifacts written by setup and analyze are not reversed.
• Language coverage — Issue #748 requests GDScript (Godot) support, which today would require new entries in SupportedLanguages and the exhaustive EXTENSION_MAP in language-detection.ts.

Vendored Grammars and Release Cadence

Some tree-sitter grammars are not prebuilt on npm, so GitNexus vendors both source and cross-built binaries — Kotlin and Swift follow this path, while Dart, Proto, and the rest use node-gyp-build to pick a prebuild at require time. The build-tree-sitter-grammars.cjs script falls back to source-build when no prebuild matches the host platform. Source: gitnexus/vendor/tree-sitter-kotlin/README.md.

Releases follow a two-track cadence: stable publishes to the latest npm dist-tag, while every non-docs merge to main triggers an automated workflow that publishes a X.Y.Z-rc.N build under the rc tag, so early adopters can install with npm install -g gitnexus@rc. Docs-only merges are intentionally skipped. Source: gitnexus/README.md.

See Also

• Agent Skills & MCP Tools — quick reference for the query / context / impact / detect_changes tools that consume the graph this pipeline produces.
• Repository Groups (gitnexus group ...) — multi-repo contract matching built on top of the same ladybug index.
• Configuration & Install — npm 11.x caveats, UNDERSTAND_QUICKLY_TOKEN, and optional FTS feature flags.

Related Pages

Related topics: Overview & Getting Started, System Architecture & Indexing Pipeline, Operations, Troubleshooting & Extensibility

AI Agent Integration & MCP Tools

Purpose and Scope

GitNexus is a graph-powered code intelligence layer that lets AI coding agents navigate, query, and reason about a codebase as a knowledge graph rather than as flat text. The package's stated goal is to "precompute every dependency, call chain, and relationship into a queryable graph" so agents can answer structural questions — *what calls this function?*, *what is the blast radius of renaming X?*, *which processes touch the changed file?* — that text search alone cannot resolve Source: [gitnexus/README.md:1-15].

The integration surface for AI agents is the Model Context Protocol (MCP). GitNexus advertises a single bin entry — gitnexus — that resolves to dist/cli/index.js and is intended to be launched as an MCP server by any MCP-compatible client Source: [gitnexus/package.json:18-22]. Supported clients documented in the README include Cursor, Claude Code, Antigravity (Google), Codex, Windsurf, Cline, and OpenCode; a frequently-upvoted community request asks for native VS Code support as well [Community: #153].

MCP Server Architecture

GitNexus exposes MCP through two transport surfaces, both backed by the same LocalBackend (the in-process adapter that wraps the on-disk LadybugDB index):

1. stdio MCP server — the canonical path used by CLI-based agents. Launched implicitly when an MCP client invokes the gitnexus binary.
2. HTTP MCP endpoint — mounted at /api/mcp on the web server. The route helper mountMCPEndpoints wires the streamable-HTTP handler into an existing Express app and returns a cleanup function for graceful shutdown Source: [gitnexus/src/server/mcp-http.ts:14-30].

The HTTP mount preserves a strict server/ → mcp/ dependency direction: session management stays inside mcp/http-transport.ts, while the web layer only knows how to delegate. Errors thrown by the handler are caught, logged, and surfaced as a JSON-RPC -32000 error so a single bad request cannot crash the web process Source: [gitnexus/src/server/mcp-http.ts:20-30].

The pipeline that feeds the MCP backend runs through well-defined phases — extracting → structure → parsing → imports → calls → heritage → scopeResolution → communities → processes → enriching → complete — shared verbatim between the CLI and the web so both surfaces observe identical progress state Source: [gitnexus-shared/src/pipeline.ts:3-20].

MCP Tools and Resources

The README enumerates the tool surface that every agent receives:

Source: [gitnexus/README.md:62-72]

Companion resources expose the same graph as read-only context: gitnexus://repos, gitnexus://repo/{name}/context, …/clusters, …/cluster/{name}, …/processes, …/process/{name}, and …/schema — agents are expected to read repos first, then drill into the relevant repo's context and schema before issuing tool calls Source: [gitnexus/README.md:74-82].

The repo parameter is optional when a single repository is indexed and required when multiple are present; callers specify it as query({search_query: "auth", repo: "my-app"}) Source: [gitnexus/README.md:84-87].

Graph Schema and Shared Contracts

Both the CLI (native LadybugDB) and the web (WASM LadybugDB) must agree on what nodes and edges exist. The single source of truth lives in gitnexus-shared:

• Node tables include File, Folder, Function, Class, Interface, Method, Community, Process, plus language-specific nodes like Struct, Enum, Trait, Impl, TypeAlias, Record, Delegate, Annotation, Constructor, Template, Module, Route, Tool. BasicBlock is reserved as the substrate for a future taint/PDG layer and is inert until that work ships Source: [gitnexus-shared/src/lbug/schema-constants.ts:9-46].
• Relationship types include CONTAINS, DEFINES, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES (with OVERRIDES kept as a legacy alias) and others. The CodeRelation table is the single edge container Source: [gitnexus-shared/src/lbug/schema-constants.ts:48-71].

The cross-file resolution algorithm (finalize) that populates these edges is SCC-aware — Tarjan SCC over the file-level import graph, processed in reverse-topological order, with a bounded fixpoint per SCC equal to |edges in SCC|. This guarantees cyclic imports terminate without hanging the indexer, which has been a recurring source of community pain (e.g., C++ projects hanging during symbol linking, [Community: #2243/#1973]) Source: [gitnexus-shared/src/scope-resolution/finalize-algorithm.ts:1-40].

Agent Skills and Onboarding

Beyond raw tools, GitNexus installs skill files that teach agents the idiomatic usage pattern: *Exploring* (navigate via graph), *Debugging* (trace call chains), *Impact Analysis* (blast radius), and *Refactoring* (plan via dependency mapping). These skills are dropped into the repo by gitnexus analyze and into the user home by gitnexus setup Source: [gitnexus/README.md:36-46].

The same analyze command also writes AGENTS.md / CLAUDE.md context files and registers Claude Code hooks. Community feedback ([#1265]) highlights that this is currently unconditional — there is no flag, env var, config file, or sentinel to opt out, which is awkward for teams that already own the contents of those files.

For headless evaluation, the eval/ harness ships three modes — baseline, native (~100ms GitNexus tools), and native_augment (recommended: tools plus auto-enriched grep output with callers, callees, and execution flows) — across models including Claude 3.5 Haiku, Claude Sonnet 4, Claude Opus 4, MiniMax M1 2.5, and GLM 4.7/5 Source: [eval/README.md:1-30].

Known Failure Modes (from community)

• Indexer hangs on large C++ repos — symbol linking can stall indefinitely on 1.6.7/1.6.8-rc; the SCC-bounded finalize algorithm is the structural mitigation, but tuning the cap per language remains open [Community: #2243, #1973].
• FTS unavailable on air-gapped installs — users on a Debian mirror without public network cannot pull the full-text search binary [Community: #2184].
• LadybugDB not initialized for repo "__wiki__" — gitnexus wiki --lang chinese triggers a wiki-internal database path that was never initialized, surfacing as a confusing init error [Community: #2225].
• Release-candidate churn — versions 1.6.8-rc.44 through 1.6.8-rc.52 plus 1.6.9-rc.9 shipped in quick succession, so users hitting MCP issues should try npm install gitnexus@rc for the latest pre-stable cut Source: [gitnexus/README.md:69-82].

See Also

• Indexing Pipeline & Knowledge Graph
• LadybugDB Schema Reference
• CLI Command Reference
• Agent Skills Catalog

Related Pages

Related topics: Overview & Getting Started, System Architecture & Indexing Pipeline, AI Agent Integration & MCP Tools

Operations, Troubleshooting & Extensibility

This page documents the operational surface of GitNexus: the CLI/MCP commands that drive day-to-day use, the failure modes that surface most often in the wild, the seams where third parties can extend the system, and the release channels that govern upgrades. It is intended for users running GitNexus in real repositories and for integrators extending its graph, language, or transport layers.

CLI Command Surface

The CLI binary is declared in gitnexus/package.json as gitnexus → dist/cli/index.js and exposes a flat command tree documented in gitnexus/README.md. The three primary entry points are:

All CLI entry points share gitnexus-shared/src/pipeline.ts, which defines the canonical PipelinePhase state machine (extracting → structure → parsing → imports → calls → heritage → scopeResolution → communities → processes → enriching → complete | error). The same enum is emitted over MCP, so a stalled run can be diagnosed identically from either surface.

Common Failure Modes & Troubleshooting

GitNexus's graph is backed by LadybugDB as the single source of truth — both the native CLI and the WASM web build consume the schema in gitnexus-shared/src/lbug/schema-constants.ts (NODE_TABLES, REL_TYPES). Most "the index broke" reports reduce to a small set of recurring symptoms.

1. `LadybugDB not initialized for repo "__wiki__". Call initLbug first.`

Reported in issue #2225 when running gitnexus wiki --lang chinese. The error means the wiki pipeline tried to open a database for a synthetic __wiki__ repo name without first calling initLbug. The fix is to ensure the wiki command path initializes a LadybugDB instance before any query is dispatched — the error string is emitted by the LadybugDB wrapper, not GitNexus itself.

2. C++ symbol-linking stalls (#2243, #1973)

C++ finalize goes through gitnexus-shared/src/scope-resolution/finalize-algorithm.ts, which runs Tarjan SCC over the file-level import graph and then a bounded fixpoint link pass capped at N = |edges in SCC|. A stall therefore indicates either a pathological SCC (the cap is exhausted before convergence) or a language-adapter hook (resolveImportTarget, expandsWildcardTo, mergeBindings) returning non-converging values. Operators can confirm by re-running gitnexus analyze with --debug and inspecting which SCC failed to terminate.

3. FTS unavailable after `npm install` on a locked-down network (#2184)

Full-text search depends on a native LadybugDB prebuild. If the registry mirror does not carry @ladybugdb/core prebuilds, the binding source-builds, which requires python3/make/g++ — the same toolchain path documented for tree-sitter-kotlin in gitnexus/vendor/tree-sitter-kotlin/README.md. The README's recommended workaround (pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus …) works for the analyze path; FTS additionally requires the prebuild to be reachable.

4. `analyze` clobbers `CLAUDE.md` / `AGENTS.md` (#1265)

Currently there is no flag, env var, config file, or sentinel to opt out of the four write surfaces. Until a config is shipped, the only safe workflow is to back up these files before analyze or to run gitnexus clean afterward and restore from VCS.

5. No full uninstall (#112)

gitnexus clean removes .gitnexus/ and unregisters from the global registry but leaves behind everything written by setup and analyze. A reverse-setup command is on the community wishlist; in the meantime, operators must manually remove skill files, hooks, and the CLAUDE.md / AGENTS.md augmentations.

Extensibility & Integration Points

GitNexus is structured so that the graph layer is runtime-agnostic and the transport / adapter layers are swappable. Concretely:

flowchart LR
  CLI[gitnexus CLI] --> Shared[gitnexus-shared<br/>(graph types, pipeline, finalize, schema)]
  MCP[MCP HTTP/stdio<br/>server/mcp-http.ts] --> Local[LocalBackend]
  Web[gitnexus-web<br/>WASM LadybugDB] --> Shared
  Local --> Ladybug[LadybugDB<br/>native]
  Web --> LadybugW[LadybugDB<br/>WASM]
  Shared --> LangAdapters[LanguageProvider<br/>hooks: resolveImportTarget,<br/>expandsWildcardTo, mergeBindings]
  Shared --> UQ[Understand-Quickly<br/>opt-in registry dispatch]

• Language adapters plug into gitnexus-shared/src/scope-resolution/finalize-algorithm.ts via three hooks: resolveImportTarget, expandsWildcardTo, mergeBindings. Adding GDScript (#748) or any other language is a matter of implementing these hooks plus the AST extractor — no changes to the cross-file finalize logic.
• Understand-Quickly registry — the opt-in publish path is defined in gitnexus-shared/src/integrations/understand-quickly.ts. It hardcodes UNDERSTAND_QUICKLY_DISPATCH_URL and UNDERSTAND_QUICKLY_EVENT_TYPE = 'sync-entry', gated by the UNDERSTAND_QUICKLY_TOKEN_ENV env var. The module is pure (no Node imports) so the same payload builder can run in CLI or browser; the network call itself lives in gitnexus/src/cli/publish.ts.
• Web ingest filter — gitnexus-web/src/lib/upload-filter.ts strips VCS metadata, node_modules, build artifacts, and oversized files (>25 MiB) before upload so the server-side analyze-upload.ts handler can ingest a sandboxed folder without re-doing that work. Operators integrating a custom uploader should mirror the same EXCLUDED_DIRS set and MAX_FILE_BYTES cap.
• Schema versioning — any new node or relation type must be added to NODE_TABLES / REL_TYPES in gitnexus-shared/src/lbug/schema-constants.ts; the comment in that file is explicit that "CLI and web must agree on these for data compatibility".

Release Channels, Vendoring & Install

GitNexus publishes to two npm dist-tags:

• latest — stable, recommended.
• rc — automated prerelease for every non-docs merge to main, formatted as X.Y.Z-rc.N (issue tracker shows v1.6.8-rc.44 through v1.6.8-rc.52 and v1.6.9-rc.9).

For tooling-hostile environments, the vendored gitnexus/vendor/ tree holds tree-sitter grammars whose npm tarballs ship source-only. The tree-sitter-kotlin/README.md explains the policy: the source is vendored so build-tree-sitter-kgrammars.cjs can cross-build prebuilds without requiring a local C/C++ toolchain. The same path now applies to Dart, Proto, Swift, and Kotlin — all registered in the workflow as kind: 'vendored'.

When upgrading across RC boundaries, the safe pattern is to re-run gitnexus analyze from a clean state; the schema is additive but LadybugDB stores are not migrated in place.

See Also

• CLI quick start and full command reference — gitnexus/README.md
• MCP server transport and resources — gitnexus/src/server/mcp-http.ts
• Scope model and finalize algorithm — gitnexus-shared/src/scope-resolution/
• Language classification (production vs experimental) — gitnexus-shared/src/scope-resolution/language-classification.ts
• Web upload sandboxing — gitnexus-web/src/lib/upload-filter.ts
• Community: #112 (uninstall), #1265 (opt-out), #153 (VS Code), #97 (local LLM CLI), #748 (GDScript)

Doramagic Pitfall Log

Found 29 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2184

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2194

3. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2243

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.
• User impact: Developers may fail before the first successful local run: Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.. Context: Observed when using node, macos
• Evidence: failure_mode_cluster:github_issue | https://github.com/abhigyanpatwari/GitNexus/issues/2225

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Install FTS feature
• User impact: Developers may fail before the first successful local run: Install FTS feature
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Install FTS feature. Context: Observed when using node, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/abhigyanpatwari/GitNexus/issues/2184

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.43
• User impact: Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.43
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.8-rc.43. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.43

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.44
• User impact: Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.44
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.8-rc.44. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.44

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.45
• User impact: Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.45
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.8-rc.45. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.45

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.46
• User impact: Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.46
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.8-rc.46. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.46

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.47
• User impact: Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.47
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.8-rc.47. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.47

11. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.48
• User impact: Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.48
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.8-rc.48. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.48

12. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.49
• User impact: Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.49
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.8-rc.49. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.49

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using GitNexus with real data or production workflows.

• Cross-repo trace: cross-file named HTTP handlers resolve to file-level, - github / github_issue
• Tree-sitter 0.25 upgrade readiness - github / github_issue
• impact callgraph mode fails when agent appends omitted optional line as - github / github_issue
• Add SystemVerilog support - github / github_issue
• HTTP provider symbolUid: wire call-site line for inline handlers in Pyth - github / github_issue
• Group bridge.lbug in-process read-only reopen fails on Windows - github / github_issue
• Optimize HttpRouteExtractor: skip source-scan for languages with full in - github / github_issue
• feat(taint): Java source/sink model slice - github / github_issue
• Add Laravel Blade Template Support - github / github_issue
• Cpp, still stuck while linking symbols in 1.6.7 - github / github_issue
• Install FTS feature - github / github_issue
• Error: LadybugDB not initialized for repo "__wiki__". Call initLbug firs - github / github_issue