Related Pages

Related topics: System Architecture, Quick Start Guide, Key Concepts

Introduction to GitNexus

GitNexus is a local-first code intelligence platform that transforms source code repositories into interactive, queryable knowledge graphs. It provides developers with deep visibility into code relationships, symbol dependencies, execution flows, and cross-repository impact analysis.

What is GitNexus?

GitNexus is a graph-based code analysis tool that:

• Clones and indexes GitHub repositories locally on your machine
• Parses source code across multiple programming languages using tree-sitter grammars
• Builds a knowledge graph representing symbols, imports, inheritance, and call relationships
• Provides AI-powered tools for querying, refactoring, and understanding code impact

Sources: gitnexus-web/src/components/AnalyzeOnboarding.tsx:12-14

The system operates with a clear data-privacy guarantee: public repositories are cloned locally, parsed entirely on your machine, and no data leaves your environment. Sources: gitnexus-web/src/components/AnalyzeOnboarding.tsx:26-27

Installation and Setup

Prerequisites

Quick Start

npm install -g gitnexus && gitnexus serve

Sources: gitnexus-web/src/components/OnboardingGuide.tsx:20-21

After starting the server, the web interface automatically detects when the server is ready and opens the graph visualization without requiring page refresh. Sources: gitnexus-web/src/components/OnboardingGuide.tsx:39-41

Architecture Overview

GitNexus follows a modular architecture with distinct phases for code ingestion, graph construction, and query execution.

graph TD
    subgraph Ingestion["Ingestion Pipeline"]
        CLONE[Git Clone] --> PARSE[Code Parsing]
        PARSE --> EXTRACT[Symbol Extraction]
        EXTRACT --> EMIT[Graph Emission]
    end
    
    subgraph Analysis["Analysis Engine"]
        EMIT --> INDEX[Workspace Index]
        INDEX --> RESOLVE[Scope Resolution]
        RESOLVE --> MODEL[Semantic Model]
    end
    
    subgraph Query["Query Layer"]
        MODEL --> MCP[Model Context Protocol]
        MCP --> TOOLS[AI Tools]
    end

Supported Languages

GitNexus uses tree-sitter for language-agnostic parsing. The following languages are supported through grammar loaders: Sources: src/core/tree-sitter/parser-loader.ts:31-48

Grammar loading is centralized in a single registry table. Adding or removing a grammar requires only one entry modification—no scattered conditional spreads or per-grammar branches. Sources: src/core/tree-sitter/parser-loader.ts:21-30

Core Pipeline Phases

1. Manifest Extraction

The manifest extraction phase processes group.yaml configuration files to identify cross-repository symbol references.

flowchart TD
    LINKS[group.yaml links] --> ME[ManifestExtractor]
    ME --> LOOP{for each link}
    LOOP --> RES[resolveSymbol]
    RES --> OK{found?}
    OK -->|yes| REF[Real symbol uid + ref]
    OK -->|no| SYN[Synthetic uid<br/>manifest::repo::cid]
    REF --> EMIT[Emit Contract + CrossLink]
    SYN --> EMIT
    EMIT --> BRIDGE[Bridge query #795]

Label-scoped queries in resolveSymbol prevent accidental cross-matches using context-aware node types: Sources: src/core/group/PIPELINE.md:14-24

• topic → (n:Function|Method|Class|Interface)
• grpc method → (n:Function|Method), service → (n:Class|Interface)
• lib → (n:Package|Module)

2. Language-Specific Pattern Extraction

GitNexus includes specialized extractors for framework-specific patterns:

#### gRPC Patterns (Node.js/TypeScript)

The gRPC pattern extractor compiles tree-sitter queries for common protobuf service patterns: Sources: src/core/group/extractors/grpc-patterns/node.ts:1-38

Bundles are pre-compiled for JavaScript, TypeScript, and TSX: Sources: src/core/group/extractors/grpc-patterns/node.ts:40-42

#### HTTP Patterns (PHP)

PHP extraction supports common web frameworks: Sources: src/core/group/extractors/http-patterns/php.ts:1-45

3. Scope Extraction

The scope extraction phase builds the fundamental parse representation used throughout the pipeline.

flowchart LR
    subgraph Input["LanguageProvider Hooks"]
        RSK[resolveScopeKind]
        BSF[bindingScopeFor]
        II[interpretImport]
        ITB[interpretTypeBinding]
        CC[classifyCallForm]
    end
    
    subgraph Process["ScopeExtractor"]
        Input --> EXTRACT[extract function]
        EXTRACT --> PF[ParsedFile]
    end
    
    PF --> OUTPUT[ownedDefs<br/>referenceSites<br/>parsedImports]

The ScopeExtractorHooks interface declares the exact subset of LanguageProvider methods used, enabling targeted testing and explicit dependency contracts. Sources: src/core/ingestion/scope-extractor.ts:38-56

4. Heritage Processing (Inheritance Analysis)

The heritage processor resolves inheritance relationships across the codebase:

graph LR
    IMP[implements] --> MAP[heritage-map.ts]
    EXT[extends] --> MAP
    MAP --> RESOLVE[resolveExtendsType]
    RESOLVE --> EMIT[implements relationship<br/>to implementor files]

Inheritance handling is language-aware with configurable strategies. For extends relationships, the system determines whether to treat them as implementation relationships based on language-specific conventions. Sources: src/core/ingestion/heritage-processor.ts:18-29

5. Reference Emission

References connect code locations to the symbols they use:

flowchart TD
    REF[Reference] --> RESOLVE[Resolve caller def]
    RESOLVE --> WALK[Walk up scope tree]
    WALK --> FOUND{Found Function-like?}
    FOUND -->|yes| EMIT[Emit edge to caller]
    FOUND -->|no| FALLBACK[Use innermost<br/>ancestor scope]
    FALLBACK --> SKIP[Skip if no def found]

Reference emission optionally flushes scope trees when INGESTION_EMIT_SCOPES=1 is set, creating: Sources: src/core/ingestion/emit-references.ts:26-35

• Scope nodes for every scope in the tree
• CONTAINS edges from parent to child scope
• DEFINES edges from scope to owned definitions
• IMPORTS edges from scope to target modules

6. Workspace Index Construction

The workspace index provides efficient reverse-lookups for scope-based queries:

The classScopeIdToDefId inverse map enables the implicit-this overload picker to skip O(C) reverse scans. Sources: src/core/ingestion/scope-resolution/workspace-index.ts:18-27

MCP Tools (Model Context Protocol)

GitNexus exposes AI tooling through the Model Context Protocol: Sources: src/mcp/resources.ts:15-27

MCP Resources

Each indexed repository exposes structured resources:

gitnexus://repo/{name}/context   → Stats, staleness check
gitnexus://repo/{name}/clusters  → All functional areas
gitnexus://repo/{name}/processes → All execution flows
gitnexus://repo/{name}/schema    → Graph schema for Cypher

Sources: src/mcp/resources.ts:29-33

Repository Management

The repo-manager.ts module handles repository registration and working directory matching:

graph TD
    REG[Register Repo] --> CWDMATCH[CwdMatch Check]
    CWDMATCH --> MATCH{Result}
    MATCH -->|path| SAME[Same directory tree]
    MATCH -->|sibling-by-remote| SIBLING[Different clone<br/>same remote]
    MATCH -->|none| NONE[No relationship]
    SIBLING --> DRIFT[Calculate commit drift]
    DRIFT --> HINT[Optional warning]

The CwdMatch interface captures: Sources: src/storage/repo-manager.ts:14-37

• Whether cwd is the registered path, a sibling clone, or unrelated
• The git toplevel when cwd is inside a work tree
• HEAD commit information for drift calculation
• Human-readable warnings when drift is detected

Git Integration

GitNexus integrates with Git for repository identification and naming: Sources: src/storage/git.ts:14-26

hasGitDir(dirPath)     // Check for .git directory
getRemoteOriginUrl(repoPath)  // Read remote.origin.url
sanitizeRepoName(name) // Prevent argument injection

The sanitizeRepoName function:

1. Strips leading dashes to prevent git command-line argument injection
2. Replaces filesystem-unsafe characters across Windows/macOS/Linux

Sources: src/storage/git.ts:45-52

Web Interface

Graph Visualization

The interactive graph displays code relationships with visual encoding: Sources: gitnexus-web/src/components/HelpPanel.tsx:7-9

Status Bar

The status bar displays indexing progress and repository state:

• Progress bar during analysis phases
• "Ready" indicator when idle
• Sponsor link for community support

Sources: gitnexus-web/src/components/StatusBar.tsx:7-18

Cross-Impact Analysis

When analyzing symbol changes, GitNexus computes affected code across repositories:

flowchart TD
    CHANGE[User changes symbol S<br/>in repo R] --> LOCAL[Local impact engine<br/>per-repo uid expansion]
    LOCAL --> IDS[Affected uid set]
    IDS --> BRIDGE[Bridge query<br/>MATCH Contract WHERE uid IN ids]
    BRIDGE --> CL[CrossLink traversal]
    CL --> OTHER[Matching contract in<br/>other repo]
    OTHER --> FDO[Fan-out impact<br/>to consuming repo]

This enables understanding how a change in one service affects dependent services through contract relationships. Sources: src/core/group/PIPELINE.md:31-40

Semantic Model Contract

The scope resolution pipeline enforces a single source of truth: Sources: src/core/ingestion/scope-resolution/contract/scope-resolver.ts:48-57

ParsedFile is the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline.

Key invariants:

• Symbol-indexed lookups live on SemanticModel for the entire codebase
• Scope-shaped lookups (which SemanticModel doesn't carry) live on WorkspaceResolutionIndex
• Edges from runScopeResolution and legacy DAG are indistinguishable to downstream consumers

Summary

GitNexus provides a comprehensive code intelligence platform with:

• Multi-language parsing via tree-sitter grammars
• Framework-specific pattern detection for gRPC, Laravel, Guzzle
• Scope-aware reference resolution with heritage tracking
• AI-accessible tooling through MCP
• Cross-repository impact analysis through contract graphs
• Local-first architecture ensuring data privacy

The system is designed for extensibility—adding new language support requires only grammar registration, and new framework patterns can be dropped into the extractors without modifying the orchestration pipeline.

Related Pages

Related topics: Introduction to GitNexus, MCP Integration

Quick Start Guide

Overview

GitNexus is a local-first code analysis tool that clones GitHub repositories, parses source code, and builds an interactive knowledge graph directly in your browser. The tool operates entirely on your machine—no data leaves your computer during analysis.

Sources: gitnexus/README.md

System Requirements

Sources: gitnexus-web/src/components/OnboardingGuide.tsx

Installation Options

GitNexus supports two installation methods depending on your workflow preferences.

Global Installation (Recommended)

Install GitNexus globally using npm for command-line access from any directory:

npm install -g gitnexus && gitnexus serve

Sources: gitnexus-web/src/components/OnboardingGuide.tsx

Local Installation

For project-specific usage, install locally within your project directory:

npm install gitnexus
npx gitnexus serve

Getting Started Workflow

The onboarding process follows a three-step workflow that automatically connects the web interface to the backend server.

flowchart TD
    A[Install GitNexus] --> B[Start Server]
    B --> C[Auto-detect Server]
    C --> D[Open Graph UI]
    
    A1[Global: npm install -g] --> B
    A2[Local: npm install] --> B
    
    B --> B1[gitnexus serve]
    B1 --> B2[Server running on port]
    
    C --> C1[Backend Polling]
    C1 --> C2[Connection Established]

Sources: gitnexus-web/src/components/OnboardingGuide.tsx

Step 1: Install and Run

Open a terminal at your project root, then install GitNexus and start the server:

npm install -g gitnexus && gitnexus serve

The server will initialize and begin listening for connections from the web interface.

Sources: gitnexus-web/src/components/OnboardingGuide.tsx

Step 2: Wait for Server Startup

The web interface automatically detects when the server is ready through backend polling. A progress indicator shows the connection status while waiting.

Sources: gitnexus-web/src/components/DropZone.tsx

Step 3: Auto-Connect

The page automatically detects the running server and establishes a WebSocket connection. No page refresh is required—the graph UI loads once the connection is established.

Analyzing a Repository

After connecting to the server, you can analyze any public GitHub repository.

flowchart LR
    A[Enter GitHub URL] --> B[Server Clones Repo]
    B --> C[Parse Code Structure]
    C --> D[Build Knowledge Graph]
    D --> E[Interactive UI]

Supported Repository Types

Sources: gitnexus-web/src/components/AnalyzeOnboarding.tsx

Analysis Workflow

1. Enter Repository URL: Paste a GitHub repository URL into the input field
2. Start Analysis: Click the analyze button to begin processing
3. Monitor Progress: View real-time progress with phase indicators
4. Cancel if Needed: Stop analysis at any point before completion

// Analysis phases observed in the codebase
type AnalysisPhase = 
  | 'cloning'      // Repository being cloned
  | 'parsing'      // Code being parsed
  | 'indexing'     // Building graph index
  | 'complete';    // Analysis finished

Sources: gitnexus-web/src/components/StatusBar.tsx

Privacy and Data Handling

Public repos only · Cloned locally by the server · No data leaves your machine

Repositories are cloned directly to your local machine. Code parsing and graph generation occur locally without external data transmission.

Sources: gitnexus-web/src/components/AnalyzeOnboarding.tsx

Managing Multiple Repositories

When multiple repositories have been analyzed, you can switch between them using the repository dropdown in the header.

flowchart TD
    A[Repository Dropdown] --> B{Select Repo}
    B -->|Same Repo| C[Stay on Current View]
    B -->|Different Repo| D[Switch Repository]
    D --> E[Load New Graph]
    
    F[Active Repository] --> G[Highlighted with accent]
    H[Other Repositories] --> I[Normal styling]

Repository Selection UI

Sources: gitnexus-web/src/components/Header.tsx

Switching Repositories

1. Open the repository dropdown menu
2. Click on any repository name
3. The graph view updates automatically to show the selected repository's knowledge graph
4. The dropdown closes after selection

// Header component handles repo switching
onClick={() => {
  if (repo.name !== projectName) onSwitchRepo?.(repo.name);
  setIsRepoDropdownOpen(false);
}}

Troubleshooting

Server Detection Issues

If the web interface fails to detect the running server:

Analysis Failures

Sources: gitnexus-web/src/components/RepoAnalyzer.tsx

Configuration

Backend Server Configuration

The server can be configured via environment variables or command-line arguments:

Sources: RUNBOOK.md

Frontend Settings

The web interface provides configuration options through the Settings panel:

• API Provider Selection: Choose between Ollama and other providers
• Model Configuration: Set the language model for Graph RAG features
• Connection Testing: Verify backend connectivity

Next Steps

After completing the quick start:

Sources: gitnexus-web/src/components/HelpPanel.tsx

Related Pages

Related topics: Knowledge Graph, Indexing Pipeline, MCP Integration

Key Concepts

GitNexus is a sophisticated code repository analysis platform that combines AST-based parsing, dependency graph construction, and semantic embeddings to provide deep insights into codebase architecture. This page covers the fundamental concepts and data structures that power GitNexus's analysis capabilities.

Related Pages

Related topics: Package Structure, Indexing Pipeline, MCP Integration, Multi-Repo Registry Architecture

System Architecture

GitNexus is a code analysis and visualization platform that provides dependency graph generation, scope-aware symbol resolution, and cross-repository impact analysis. The system architecture is designed around a multi-stage ingestion pipeline that transforms source code into a queryable knowledge graph.

Overview

GitNexus operates as a client-server application:

• Backend Server (gitnexus/src/): A Node.js server responsible for code ingestion, AST parsing, scope resolution, and graph construction
• Web Frontend (gitnexus-web/src/): A React-based visualization layer that renders the interactive dependency graph

The architecture emphasizes separation of concerns: language-specific extraction logic is isolated from the core orchestration, enabling extensibility without modifying the main pipeline.

Sources: gitnexus/src/core/group/PIPELINE.md

Core Architectural Principles

Single Source of Truth

The ParsedFile model (defined in gitnexus-shared/src/scope-resolution/parsed-file.ts) serves as the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline. Scope-resolution passes must not build a parallel parse representation.

Sources: gitnexus-shared/src/scope-resolution/parsed-file.ts:1-40

Same-Graph Guarantee

Edges emitted by runScopeResolution and edges emitted by the legacy DAG are indistinguishable to downstream consumers:

This ensures transparent interoperability between both code paths.

Sources: gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts

Language Extensibility

The orchestrator never imports a grammar directly. Adding support for a new language or framework requires only:

1. Dropping one file in *-patterns/ directory
2. Registering it in index.ts

No orchestrator edits are required.

Sources: gitnexus/src/core/group/PIPELINE.md

Ingestion Pipeline

The ingestion pipeline processes source code through a series of stages to build the dependency graph.

graph TD
    subgraph Ingestion
        FS[File System] --> SCOPE[Scope Extractor]
        SCOPE --> PARSE[Parsing Phase]
        PARSE --> CALLS[Call Processor]
        CALLS --> HERITAGE[Heritage Processor]
        HERITAGE --> FINALIZE[Graph Finalization]
    end
    
    subgraph Language Support
        PARSER[Parser Loader] --> TS[Tree-sitter Grammars]
        TS --> LANG[Language Registry]
        LANG --> PROVIDER[Language Providers]
    end
    
    SCOPE -.-> PROVIDER
    PARSE -.-> PROVIDER
    CALLS -.-> PROVIDER
    HERITAGE -.-> PROVIDER

Stage 1: Scope Extraction

The ScopeExtractor is the central, source-agnostic driver that converts language provider captures into ParsedFile artifacts.

Key responsibilities:

• Build scope tree from @scope.* matches
• Maintain structural invariants (non-module has parent; parent contains child)
• Produce ParsedFile containing: scopes, parsedImports, localDefs, referenceSites

Design principles:

• Source-agnostic: Consumes CaptureMatch[] from providers
• One AST walk per language: Providers handle AST traversal internally
• Pure-ish: Same matches produce same ParsedFile output
• Centralized invariant enforcement via buildScopeTree

Sources: gitnexus/src/core/ingestion/scope-extractor.ts:1-50

Stage 2: Call Resolution

The call processor resolves function and method calls to their definitions.

graph LR
    subgraph Input
        FILES[Source Files] --> LANG[Language Detection]
    end
    
    subgraph Processing
        LANG --> PARSE[Parse with Tree-sitter]
        PARSE --> QUERY[Execute Queries]
        QUERY --> MATCHES[Capture Matches]
        MATCHES --> RESOLVE[Resolve Calls to Defs]
    end
    
    subgraph Output
        RESOLVE --> EDGES[Call Edges in Graph]
    end

Registry-Primary Language Gate:

For languages marked as isRegistryPrimary, scope-based phase owns CALLS processing, bypassing the legacy call processor:

// Registry-primary gate: scope-based phase owns CALLS for this lang.
if (isRegistryPrimary(language)) continue;

Sources: gitnexus/src/core/ingestion/call-processor.ts:1-50

Stage 3: Heritage Processing

Heritage processing resolves class inheritance relationships (extends and implements).

Heritage types:

• extends → creates EXTENDS relationship
• implements → creates IMPLEMENTS relationship

Processing logic:

if (h.kind === 'extends') {
  const { type: relType, idPrefix } = resolveExtendsType(
    h.parentName,
    h.filePath,
    ctx,
    getHeritageStrategyForLanguage(fileLanguage),
  );
  // Create relationship with confidence score
  graph.addRelationship({
    type: relType,
    confidence: Math.sqrt(child.confidence * parent.confidence),
  });
}

Sources: gitnexus/src/core/ingestion/heritage-processor.ts:1-60

Stage 4: Heritage Map Construction

The heritage map tracks class/interface inheritance for Method Resolution Order (MRO) calculations.

Key data structures:

Public API:

• getParentEntries(childNodeId) → returns readonly ParentEntry[]
• getParents(childNodeId) → returns deduplicated string[]

Sources: gitnexus/src/core/ingestion/model/heritage-map.ts:1-60

Parser Architecture

Tree-sitter Integration

GitNexus uses Tree-sitter for universal AST parsing across supported languages.

Grammar loading strategy:

const SOURCES: Record<string, GrammarSource> = {
  [SupportedLanguages.JavaScript]: {
    load: () => _require('tree-sitter-javascript'),
    unavailableNote: 'JavaScript parsing requires `tree-sitter-javascript`...',
  },
  [SupportedLanguages.TypeScript]: {
    load: () => _require('tree-sitter-typescript').typescript,
  },
  [`${SupportedLanguages.TypeScript}:tsx`]: {
    load: () => _require('tree-sitter-typescript').tsx,
  },
  [SupportedLanguages.Python]: {
    load: () => _require('tree-sitter-python'),
  },
  // Additional languages...
};

Configuration rules:

• Grammars must be in dependencies (not optionalDependencies)
• Failures indicate real install problems and should never be hidden

Sources: gitnexus/src/core/tree-sitter/parser-loader.ts:1-80

Supported Languages

The system supports multiple programming languages through a registry pattern:

Workspace Index

The workspace index provides O(totalScopes) build-time indexing for efficient runtime lookups.

Interface:

export interface WorkspaceResolutionIndex {
  /** Class def `nodeId` → that class's `Scope`. */
  readonly classScopeByDefId: ReadonlyMap<string, Scope>;
  
  /** Inverse: class `Scope.id` → class def `nodeId`. */
  readonly classScopeIdToDefId: ReadonlyMap<string, string>;
}

Semantic model lookups:

This split preserves the single-source-of-truth invariant: symbol-indexed lookups live on SemanticModel; scope-shaped lookups live on WorkspaceResolutionIndex.

Sources: gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:1-50

Pattern Extraction System

Language Pattern Bundles

Each language has pattern bundles compiled from Tree-sitter query specifications:

Example: PHP HTTP Patterns

const PHP_PATTERNS: PhpPatternBundle = {
  laravelRoute: mk(LARAVEL_ROUTE_SPEC, 'laravel-route'),
  httpFacade: mk(HTTP_FACADE_SPEC, 'http-facade'),
  guzzleMember: mk(GUZZLE_MEMBER_SPEC, 'guzzle-member'),
  fileGetContents: mk(FILE_GET_CONTENTS_SPEC, 'file-get-contents'),
};

Example: gRPC Patterns (Node.js/TypeScript)

const JAVASCRIPT_BUNDLE = compileBundle(JavaScript, 'javascript-grpc');
const TYPESCRIPT_BUNDLE = compileBundle(TypeScript.typescript, 'typescript-grpc');
const TSX_BUNDLE = compileBundle(TypeScript.tsx, 'tsx-grpc');

Pattern categories:

• HTTP route handlers
• gRPC service clients
• Framework-specific patterns (Laravel, Guzzle, etc.)
• Import/export declarations
• Call expressions

Sources: gitnexus/src/core/group/extractors/http-patterns/php.ts:1-50

Data Models

ParsedFile Structure

interface ParsedFile {
  readonly scopes: Scope[];
  readonly parsedImports: ParsedImport[];
  readonly localDefs: LocalDef[];
  readonly referenceSites: ReferenceSite[];
}

What ParsedFile deliberately does NOT carry:

• Linked ImportEdges (finalize output)
• ScopeTree instance (callers build from scopes)

Sources: gitnexus-shared/src/scope-resolution/parsed-file.ts:1-60

Git Integration

The system integrates with Git repositories for analysis:

Key functions:

Security considerations:

• Leading dashes are stripped to prevent git command-line argument injection
• Characters unsafe for directory names are replaced with underscores
• execSync uses stdio: ['ignore', 'pipe', 'ignore'] to prevent information leakage

Sources: gitnexus/src/storage/git.ts:1-80

Manifest Extraction

The manifest extraction system links contracts across repositories:

flowchart TD
    Y[group.yaml links] --> ME[ManifestExtractor]
    ME --> LOOP{for each link}
    LOOP --> RES[resolveSymbol<br/>label-scoped Cypher]
    RES --> OK{found?}
    OK -->|yes| REF[real symbol uid + ref]
    OK -->|no| SYN[synthetic uid<br/>manifest::repo::cid]
    
    REF --> EMIT[emit provider + consumer<br/>Contract objects + CrossLink]
    SYN --> EMIT
    
    EMIT --> BRIDGE[(bridge.lbug<br/>#795)]

Label-scoped queries prevent accidental cross-matches:

• topic → (n:Function|Method|Class|Interface)
• grpc method → (n:Function|Method), service → (n:Class|Interface)
• lib → (n:Package|Module)

Sources: gitnexus/src/core/group/PIPELINE.md

Cross-Impact Query System

The cross-impact query system tracks dependencies across repository boundaries:

flowchart TD
    U[User changes symbol S<br/>in repo R] --> LI[Local impact engine<br/>per-repo uid expansion]
    LI --> IDS[Affected uid set]
    
    IDS --> BR[Bridge query<br/>MATCH Contract WHERE uid IN ids]
    BR --> CL[CrossLink traversal]
    CL --> OTHER[Matching contract in<br/>other repo]
    
    OTHER --> FE[Fan-out impact<br/>to consuming repo]

This enables developers to understand the blast radius of changes across service boundaries.

Sources: gitnexus/src/core/group/PIPELINE.md

Frontend Architecture

The web frontend provides the visualization layer:

Key components:

Connection states:

• onboarding — initial setup phase
• analyze — server up but no repos indexed
• landing — server up with indexed repos
• success / loading — operation in progress

Sources: gitnexus-web/src/components/DropZone.tsx:1-50

Error Handling and Resilience

Language unavailability:

if (!isLanguageAvailable(language)) {
  if (skippedByLang) {
    skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);
  }
  continue;
}

Parse error handling:

try {
  tree = parseSourceSafe(parser, parseContent, undefined, {
    bufferSize: getTreeSitterBufferSize(parseContent),
  });
} catch (parseError) {
  continue; // Skip malformed files
}

Event loop yielding:

if (i % 20 === 0) await yieldToEventLoop();

Files are processed in batches of 20 with event loop yields to prevent UI blocking during large repository analysis.

Sources: gitnexus/src/core/ingestion/call-processor.ts:1-60

Performance Considerations

Summary

GitNexus implements a modular, extensible code analysis architecture:

1. Pipeline-driven ingestion with clearly delineated stages
2. Language-agnostic core with pluggable pattern extractors
3. Single semantic model ensuring consistency across analysis paths
4. Cross-repository impact tracking for change propagation analysis
5. Tree-sitter-based parsing with efficient grammar loading

The architecture prioritizes extensibility (new languages = new pattern files), performance (caching, batching, indexing), and correctness (invariant enforcement, same-graph guarantees).

Related Pages

Related topics: System Architecture

Package Structure

GitNexus is organized as a monorepo with four distinct packages, each serving a specific role in the codebase intelligence platform. The architecture separates concerns between the backend analysis engine, web interface, shared type definitions, and evaluation tooling.

Monorepo Overview

graph TD
    subgraph "GitNexus Monorepo"
        Web[gitnexus-web<br/>React Frontend]
        Core[gitnexus<br/>Core Engine]
        Shared[gitnexus-shared<br/>Shared Types]
        Eval[eval<br/>Evaluation]
    end
    
    Web <--> Shared
    Core <--> Shared
    Core <--> Web
    Eval --> Core

Package Breakdown

gitnexus — Core Engine

The core package is the backbone of GitNexus, handling all code analysis, parsing, and knowledge graph construction.

Directory Structure

gitnexus/src/
├── cli/                    # Command-line interface commands
│   ├── index.ts           # CLI entry point with command registration
│   ├── wiki.js            # Wiki generation command
│   ├── augment.js         # Search pattern augmentation
│   └── publish.js         # Registry notification
├── core/
│   ├── ingestion/         # Code parsing and analysis
│   │   ├── model/        # Heritage map generation
│   │   ├── scope-extractor.ts
│   │   ├── heritage-processor.ts
│   │   └── scope-resolution/
│   │       └── workspace-index.ts
│   ├── tree-sitter/      # Parser loader and language support
│   │   └── parser-loader.ts
│   └── group/            # Module extraction and contracts
│       ├── extractors/
│       │   └── grpc-patterns/
│       │       └── node.ts
│       └── PIPELINE.md
└── storage/
    └── git.ts            # Git operations utility

Key Modules

#### Ingestion Pipeline

The ingestion system processes source code and builds the knowledge graph:

flowchart TD
    A[Source Files] --> B[Language Detection]
    B --> C[Tree-sitter Parsing]
    C --> D[AST Analysis]
    D --> E[Scope Extraction]
    E --> F[Heritage Processing]
    F --> G[Knowledge Graph]

• Scope Extractor (scope-extractor.ts): Extracts bindings, imports, and symbol references using language-specific providers.
• Heritage Processor (heritage-processor.ts): Resolves class inheritance and interface implementation relationships.
• Workspace Index (workspace-index.ts): Builds O(totalScopes) index for class scope lookups.

#### Tree-sitter Parser Loader

The parser loader (parser-loader.ts) provides language-specific parsing through tree-sitter grammars:

Sources: parser-loader.ts:26-90

#### CLI Commands

The CLI (index.ts) provides multiple commands:

• serve — Start the backend server
• ingest <repoPath> — Analyze and index a repository
• query <search_query> — Search the knowledge graph
• wiki — Generate documentation from module structure
• augment <pattern> — Add knowledge graph context to search
• publish [path] — Notify registry of fresh index

Sources: index.ts

gitnexus-web — Frontend Application

The web package provides the interactive UI for visualizing and exploring the knowledge graph.

Component Architecture

gitnexus-web/src/
└── components/
    ├── Header.tsx          # Navigation, repo switching
    ├── DropZone.tsx        # Server connection, initial probe
    ├── OnboardingGuide.tsx # Setup wizard
    ├── AnalyzeOnboarding.tsx # GitHub repo analyzer
    ├── HelpPanel.tsx       # Contextual help, AI queries
    └── StatusBar.tsx       # Progress, status indicators

Key Components

#### Connection States

The DropZone component manages backend connection through polling:

type ConnectionPhase = 'onboarding' | 'analyze' | 'landing' | 'success' | 'loading';

Sources: DropZone.tsx

#### Help Panel Modes

The HelpPanel provides contextual guidance for different exploration modes:

• Graph view — Node size meaning, edge direction, click interactions
• Search & filter — Query syntax guidance
• Nexus AI — Semantic query examples, "Semantic Ready" status

Sources: HelpPanel.tsx

gitnexus-shared — Shared Type System

The shared package defines TypeScript interfaces, types, and utilities used across both the core engine and web frontend.

Core Types

Sources: scope-extractor.ts:1-25

Utility Functions

The shared package exports utility functions used throughout the codebase:

• buildPositionIndex — Position indexing for source locations
• buildScopeTree — Scope hierarchy construction
• canParentScope — Scope relationship validation
• makeScopeId — Scope identifier generation
• isClassLike — Class-like scope detection

eval — Evaluation Harness

The eval package provides benchmarking and evaluation tooling for the analysis engine. It validates correctness of ingestion, querying, and relationship detection.

Dependency Flow

graph LR
    Shared --> Core
    Shared --> Web
    Core --> Web
    Eval --> Core
    
    subgraph "gitnexus-shared"
        Shared
    end
    
    subgraph "gitnexus"
        Core
    end
    
    subgraph "gitnexus-web"
        Web
    end
    
    subgraph "eval"
        Eval
    end

Data Models

LanguageProvider Interface

The LanguageProvider interface defines hooks for language-specific analysis:

type ScopeExtractorHooks = Pick<
  LanguageProvider,
  | 'resolveScopeKind'
  | 'bindingScopeFor'
  | 'interpretImport'
  | 'interpretTypeBinding'
  | 'classifyCallForm'
>;

Sources: scope-extractor.ts:55-66

WorkspaceResolutionIndex

Build-time index for efficient scope lookups:

interface WorkspaceResolutionIndex {
  readonly classScopeByDefId: ReadonlyMap<string, Scope>;
  readonly classScopeIdToDefId: ReadonlyMap<string, string>;
}

Sources: workspace-index.ts

Adding New Language Support

To add support for a new language:

``typescript [SupportedLanguages.NewLang]: { load: () => _require('tree-sitter-newlang'), unavailableNote: 'NewLang parsing requires tree-sitter-newlang.', }, ``

1. Add grammar to SOURCES in parser-loader.ts:

1. Register patterns in the group extractors if needed for module extraction.

1. Implement language-specific hooks in LanguageProvider if the default extraction is insufficient.

Sources: parser-loader.ts

Related Pages

Related topics: System Architecture, Multi-Repo Registry Architecture

MCP Integration

GitNexus provides a Model Context Protocol (MCP) server that exposes the knowledge graph as a set of tools and resources for AI code assistants like Claude. This integration enables AI assistants to query repository structure, understand code relationships, and perform impact analysis directly within their workflow.

Overview

The MCP server operates over stdio (standard input/output), making it compatible with any editor or IDE that supports the MCP protocol. When connected, AI assistants can leverage GitNexus's indexed knowledge graph to provide context-aware responses about your codebase.

graph TD
    A["AI Editor<br/>(Claude, Cursor, etc.)"] -->|"MCP Protocol<br/>stdio"| B["GitNexus MCP Server"]
    B --> C["gitnexus mcp"]
    C --> D["Knowledge Graph DB<br/>(Indexed Repos)"]
    
    E["Tool Requests"] --> B
    B --> F["Query Results"]
    
    G["Resource Requests"] --> B
    B --> H["Repo Context<br/>Clusters<br/>Processes"]

Sources: gitnexus/README.md:17

Starting the MCP Server

Command-Line Usage

gitnexus mcp

This starts the MCP server in stdio mode, serving all indexed repositories. The server listens for JSON-RPC requests from connected clients and returns structured responses.

Sources: gitnexus/README.md:17

Startup Behavior

The MCP server entry point implements intelligent binary resolution:

1. Preferred: Uses the globally-installed gitnexus binary (starts in ~1 second)
2. Fallback: Uses npx -y gitnexus@<version> when the binary isn't on PATH

The npx fallback is slower due to cold-cache installation of native dependencies (can exceed 30 seconds), which may exceed Claude Code's MCP connection timeout. The binary path is resolved at module load time and persisted in user config.

function getMcpEntry() {
  const bin = resolveGitnexusBin();

  if (bin) {
    return { command: bin, args: ['mcp'] };
  }

  // Fallback: npx (works without a global install, but slow cold-start)
  if (process.platform === 'win32') {
    return {
      command: 'cmd',
      args: ['/c', 'npx', '-y', NPX_REF, 'mcp'],
    };
  }
  // ...
}

Sources: gitnexus/src/cli/setup.ts:45-62

MCP Tools

The MCP server exposes a comprehensive set of tools for querying and manipulating the knowledge graph. Each tool corresponds to a specific capability within GitNexus.

Available Tools

Sources: gitnexus/src/mcp/resources.ts:47-56

Tool Execution Flow

sequenceDiagram
    participant Editor as AI Editor
    participant MCP as MCP Server
    participant Graph as Knowledge Graph
    
    Editor->>MCP: tool_request(query, "auth module")
    MCP->>MCP: Parse request & validate
    MCP->>Graph: Execute graph query
    Graph-->>MCP: Query results with execution flows
    MCP-->>Editor: Structured JSON response

MCP Resources

Resources provide read-only access to repository metadata and graph schema information. They follow a gitnexus:// URI scheme for addressing.

Resource Types

Resource Content Format

Each resource returns structured Markdown documentation. For example, the context resource includes:

This project is indexed by GitNexus as **{repo.name}** ({stats.nodes || 0} symbols, {stats.edges || 0} relationships, {stats.processes || 0} execution flows).

Sources: gitnexus/src/mcp/resources.ts:30-36

Editor Integration

Claude Desktop Configuration

For Claude Desktop integration, add the GitNexus MCP server to your configuration:

{
  "mcpServers": {
    "gitnexus": {
      "command": "gitnexus",
      "args": ["mcp"]
    }
  }
}

Editor Hook System

GitNexus includes Claude-specific hooks that integrate with the MCP server:

graph LR
    A["gitnexus-hook.cjs"] -->|Integration| B["Claude Code"]
    A -->|Query| C["Knowledge Graph"]
    B -->|Requests| C

The hook enables real-time code context awareness during editing sessions, allowing Claude to reference repository structure without manual context switching.

Sources: gitnexus/hooks/claude/gitnexus-hook.cjs

Architecture

Component Overview

graph TD
    subgraph "MCP Layer"
        A["server.ts<br/>Request Handler"] --> B["tools.ts<br/>Tool Registry"]
        A --> C["resources.ts<br/>Resource Provider"]
    end
    
    subgraph "Core Services"
        B --> D["runFullAnalysis"]
        B --> E["WikiGenerator"]
        C --> F["RepoRegistry"]
    end
    
    subgraph "Data Layer"
        D --> G["LadybugDB<br/>(SQLite)"]
        F --> G
    end

Request Processing

1. Connection: Client establishes stdio connection to gitnexus mcp
2. Initialization: Server sends protocol handshake with available capabilities
3. Tool Invocation: Client sends tools/call requests
4. Query Execution: Server routes to appropriate handler (graph DB, file system)
5. Response: Structured JSON-RPC response returned via stdio

Use Cases

Semantic Code Understanding

When asking Claude questions like "Which files depend on the auth module?", the MCP server:

1. Receives the query tool call
2. Searches the knowledge graph for import relationships
3. Returns execution flows and dependency chains

Impact Analysis

Before making changes, use the impact tool to understand the blast radius:

• Depth 1: Direct dependencies
• Depth 2: Transitive dependencies
• Depth 3: Full impact tree with confidence scores

Change Detection

The detect_changes tool compares current working directory state against the indexed snapshot, returning:

• Modified files
• Added imports/exports
• Removed dependencies

Configuration

Multi-Repository Support

The MCP server serves all indexed repositories registered in the global registry. Use gitnexus list to see available repos:

gitnexus list                    # List all indexed repositories
gitnexus status                  # Show index status for current repo

Sources: gitnexus/README.md:20-24

Binaries on Windows

On Windows, gitnexus may have multiple entries from where:

• POSIX shell script (not directly executable)
• .cmd/.bat wrapper (preferred for spawn())

The setup code prefers the wrapper to ensure reliable execution:

const cmdLine = lines.find((l) => /\.(cmd|bat)$/i.test(l));
return cmdLine || lines[0] || null;

Sources: gitnexus/src/cli/setup.ts:21-24

Summary

The MCP Integration layer transforms GitNexus from a standalone analysis tool into a collaborative AI assistant. By exposing the knowledge graph through the Model Context Protocol, it enables:

• Deep Context: AI understands codebase structure, not just file names
• Impact Awareness: Changes can be validated against dependency graphs
• Cross-Repo Intelligence: Multi-repository analysis through unified queries
• Workflow Integration: Seamless incorporation into daily editing tasks

The architecture prioritizes fast startup (global binary preference) and reliable cross-platform execution, making it practical for CI/CD environments and interactive development alike.

Related Pages

Related topics: MCP Integration, Knowledge Graph

Multi-Repo Registry Architecture

Overview

The Multi-Repo Registry is GitNexus's core system for managing multiple indexed repositories within a single global registry. It provides the foundation for repository discovery, identity resolution, and multi-repo querying across the CLI, MCP server, and web interface.

The registry persists as ~/.gitnexus/registry.json, storing metadata for each indexed repository including its path, name, last indexed commit, and statistics about the generated knowledge graph (nodes, edges, processes).

Registry Data Model

RegistryEntry Interface

Each entry in the registry represents a single indexed repository:

Sources: gitnexus/src/storage/repo-manager.ts:60-70

CwdMatch Interface

The registry provides a matching interface to resolve the current working directory against indexed repositories:

export interface CwdMatch {
  match: 'path' | 'sibling-by-remote' | 'none';
  entry?: RegistryEntry;
  cwdGitRoot?: string;
  cwdHead?: string;
  drift?: number;
  hint?: string;
}

The CwdMatch interface supports three match scenarios:

Sources: gitnexus/src/storage/repo-manager.ts:200-220

Name Resolution Precedence

GitNexus employs a four-tier name resolution strategy to determine the registry name for an indexed repository:

graph TD
    A[Start: Determine registry name] --> B{T Explicit --name provided?}
    B -->|Yes| C[Use explicit name]
    B -->|No| D{Existing entry with preserved alias?}
    D -->|Yes| E[Use preserved alias]
    D -->|No| F{remote.origin.url available?}
    F -->|Yes| G[Derive name from remote URL]
    F -->|No| H[Use path.basename]
    
    C --> I[Store in registry]
    E --> I
    G --> I
    H --> I

Resolution Tiers

Sources: gitnexus/src/storage/repo-manager.ts:290-310

Git Worktree Support

A key architectural concern is handling git worktrees correctly. When running gitnexus analyze inside a linked worktree, the system uses git rev-parse --git-common-dir to derive the canonical repository root, preventing worktrees from being registered under their directory slug (e.g., wt-feature) instead of the actual repo name (e.g., repo).

export const resolveRepoIdentityRoot = (fromPath: string): string => {
  const resolved = path.resolve(fromPath);
  const canonical = getCanonicalRepoRoot(resolved);
  if (!canonical) return resolved;
  if (canonical === resolved) return canonical;
  if (hasGitDir(resolved)) return canonical; // linked worktree
  return resolved; // arbitrary subdir → preserve as-is
};

Without this, each worktree would re-register as a "different" project, causing AGENTS.md to be rewritten with the wrong MCP URI and silently accumulating duplicate registry entries.

Sources: gitnexus/src/storage/git.ts:90-110

Registry Operations

Registration Flow

sequenceDiagram
    participant CLI as gitnexus analyze
    participant RM as repo-manager
    participant FS as filesystem
    participant Git as git utilities
    
    CLI->>RM: registerRepo(repoPath, opts)
    RM->>Git: getRemoteOriginUrl(repoPath)
    RM->>Git: resolveRepoIdentityRoot(repoPath)
    RM->>RM: resolveName(precedence tiers)
    RM->>RM: checkDuplicateName()
    alt duplicate found & !allowDuplicateName
        RM-->>CLI: throw RegistryNameCollisionError
    else allowed or no duplicate
        RM->>FS: persist to registry.json
        RM-->>CLI: return resolved name
    end

#### Registration Options

The duplicate-name guard only fires when the user explicitly passes a name; un-aliased basename collisions continue to register silently so existing users see no behavior change.

Sources: gitnexus/src/core/run-analyze.ts:45-60

Listing Repositories

The gitnexus list command displays all indexed repositories with collision-aware formatting:

export const listCommand = async () => {
  const entries = await listRegisteredRepos({ validate: true });
  const nameCounts = new Map<string, number>();
  
  for (const entry of entries) {
    const key = entry.name.toLowerCase();
    nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
  }
  
  for (const entry of entries) {
    const hasCollision = (nameCounts.get(entry.name.toLowerCase()) ?? 0) > 1;
    const header = hasCollision ? `${entry.name}  (${entry.path})` : entry.name;
    // display with path disambiguation for collisions
  }
};

Entries with name collisions display their path to disambiguate:

  myapp  (/projects/myapp)
  myapp  (/worktrees/myapp-feature)

Sources: gitnexus/src/cli/list.ts:15-50

Repository Switching (Web Interface)

The web interface supports switching between indexed repositories via a dropdown menu. The Header component renders available repos with an "active" indicator for the current project:

{availableRepos.map((repo) => (
  <div key={repo.name} className="...">
    <button onClick={() => onSwitchRepo?.(repo.name)}>
      <span className="font-mono text-sm">{repo.name}</span>
      {repo.name === projectName && (
        <span className="text-[10px] text-accent">active</span>
      )}
    </button>
  </div>
))}

Sources: gitnexus-web/src/components/Header.tsx:1-50

Error Handling

RegistryNameCollisionError

When two different repository paths attempt to register under the same name without the --allow-duplicate-name flag, the system throws RegistryNameCollisionError with actionable guidance:

Registry name collision:
  "myapp" is already used by "/projects/myapp".

Options:
  • Pick a different alias:  gitnexus analyze --name <alias>
  • Allow the duplicate:     gitnexus analyze --allow-duplicate-name

Sources: gitnexus/src/cli/analyze.ts:30-45

AnalysisNotFinalizedError

If the analysis pipeline fails to complete, users receive diagnostic guidance:

1. Re-run gitnexus analyze — transient native errors often clear on retry
2. Inspect the storage path for leftover lbug.wal indicating an aborted write
3. Run with NODE_OPTIONS="--max-old-space-size=8192 --trace-exit" for detailed tracing

Sources: gitnexus/src/cli/analyze.ts:50-70

MCP Server Integration

The MCP server exposes registry information through the gitnexus://repo/{name}/* URI scheme:

Sources: gitnexus/src/mcp/resources.ts:40-55

Configuration Storage

Registry metadata is stored alongside the index in the GitNexus storage directory:

const { registryPath, indexPath, metaPath } = getStoragePaths(repoName, repoPath);

The registry file (registry.json) maintains the authoritative list of all indexed repositories and is the single source of truth for repository discovery across CLI, MCP, and web components.

Summary

The Multi-Repo Registry Architecture provides:

• Centralized repository tracking via ~/.gitnexus/registry.json
• Intelligent name resolution with support for aliases, git remotes, and worktrees
• Collision detection with graceful degradation via --allow-duplicate-name
• Unified discovery across CLI (list, query), MCP (list_repos), and web interfaces
• Cross-repo intelligence enabling queries and context to span multiple repositories

Related Pages

Related topics: Knowledge Graph, Search System

Indexing Pipeline

The Indexing Pipeline is the core ingestion system that transforms source code repositories into a graph-based representation. It scans, parses, extracts semantic relationships, and builds the knowledge graph that powers GitNexus's dependency visualization and impact analysis capabilities.

Overview

The pipeline operates as a multi-phase execution engine where each phase depends on the output of previous phases. It processes source files through sequential stages, extracting code symbols, relationships, and metadata to construct the semantic graph.

graph TD
    A[Source Files] --> B[Structure Phase]
    B --> C[Parse Phase]
    C --> D[Scope Extraction]
    D --> E[Finalize Phase]
    E --> F[Call Processing]
    E --> G[Heritage Processing]
    D --> H[Communities Detection]
    F --> I[Graph Completion]
    G --> I
    H --> I
    I --> J[Indexed Graph]

Sources: gitnexus/src/core/group/PIPELINE.md

Pipeline Architecture

Phase Execution Model

The pipeline is built on a PipelinePhase<T> abstraction where each phase declares its dependencies and implements an execute function:

const pipelinePhase: PipelinePhase<ParseOutput> = {
  name: 'parse',
  deps: ['structure', 'markdown', 'cobol'],
  async execute(
    ctx: PipelineContext,
    deps: ReadonlyMap<string, PhaseResult<unknown>>,
  ): Promise<ParseOutput> { /* ... */ }
};

Sources: gitnexus/src/core/ingestion/pipeline-phases/parse.ts:1-24

Pipeline Context

The PipelineContext carries shared state across phases:

Phase Breakdown

Structure Phase

The entry point that discovers and classifies files in the repository. It builds the initial file inventory with metadata including paths, sizes, and detected languages.

Parse Phase

The parse phase transforms source files into structured AST representations using tree-sitter parsers. It processes files in a chunked, parallel manner to handle large repositories efficiently.

const result = await runChunkedParseAndResolve(
  ctx.graph,
  scannedFiles,
  allPaths,
  totalFiles,
  ctx.repoPath,
  ctx.pipelineStart,
  ctx.onProgress,
  ctx.options,
);

Sources: gitnexus/src/core/ingestion/pipeline-phases/parse.ts:17-24

#### Parsing Processor

The parsing-processor.ts handles the actual file parsing and extraction:

const merged = mergeChunkResults(graph, symbolTable, chunkResults);

Sources: gitnexus/src/core/ingestion/parsing-processor.ts:1-50

Scope Extraction Phase

Scope extraction produces ParsedFile objects that represent the semantic structure of each source file. This is the per-file, parallelizable boundary between extraction and cross-file resolution.

#### ParsedFile Structure

interface ParsedFile {
  readonly scopes: Scope[];           // All scopes in the file
  readonly parsedImports: ParsedImport[];  // Raw imports before resolution
  readonly localDefs: SymbolDefinition[];  // Structurally declared definitions
  readonly referenceSites: ReferenceSite[]; // Pre-resolution usage facts
}

Sources: gitnexus-shared/src/scope-resolution/parsed-file.ts:1-30

The ParsedFile deliberately does NOT carry:

• Linked ImportEdges (those are finalize output)
• A ScopeTree instance (callers build one from scopes)

#### Scope Extraction Hooks

Language providers implement these hooks for scope extraction:

export type ScopeExtractorHooks = Pick<
  LanguageProvider,
  | 'resolveScopeKind'
  | 'bindingScopeFor'
  | 'interpretImport'
  | 'interpretTypeBinding'
  | 'classifyCallForm'
>;

Sources: gitnexus/src/core/ingestion/scope-extractor.ts:30-48

Call Processing Phase

Call processing extracts function/method invocations and builds dispatch information. It works with language providers to query ASTs using tree-sitter queries:

interface PreparedFile {
  language: SupportedLanguages;
  provider: ReturnType<typeof getProvider>;
  tree: ReturnType<typeof parser.parse>;
  matches: ReturnType<Parser.Query['matches']>;
  parentMap: ReadonlyMap<string, readonly string[]>;
  typeEnv: ReturnType<typeof buildTypeEnv>;
}

Sources: gitnexus/src/core/ingestion/call-processor.ts:1-20

The call processor skips registry-primary languages since scope-based phases own CALLS extraction for those languages.

Heritage Processing Phase

Heritage processing extracts inheritance relationships (extends/implements) and resolves them into graph edges:

graph TD
    H[Heritage Record] -->|extends| E{Extends Type Check}
    H -->|implements| I{Is Implements}
    E -->|IMPLEMENTS| I
    E -->|CLASS| C[Add Extends Edge]
    I -->|Yes| Impl[Add Implements Edge]

For extends relationships, the processor determines the relationship type based on the language:

const { type: relType, idPrefix } = resolveExtendsType(
  h.parentName,
  h.filePath,
  ctx,
  getHeritageStrategyForLanguage(fileLanguage),
);

Sources: gitnexus/src/core/ingestion/heritage-processor.ts:1-50

Communities Detection Phase

Detects code communities and modules within the codebase, enabling grouped visualization and analysis.

Scope Resolution

Resolution Indexes

After the main parsing phases, scope resolution builds cross-file indexes:

export interface ScopeResolutionIndexes {
  readonly scopeTree: ScopeTree;
  readonly defs: DefIndex;
  readonly qualifiedNames: QualifiedNameIndex;
  readonly moduleScopes: ModuleScopeIndex;
  readonly methodDispatch: MethodDispatchIndex;
  readonly imports: ImportEdge[];
  readonly bindings: BindingIndex;
  readonly referenceSites: ReferenceSite[];
  readonly stats: FinalizeStats;
}

Sources: gitnexus/src/core/ingestion/scope-resolution-indexes.ts:1-35

Workspace Resolution Index

The workspace index provides fast lookups for class and module scopes:

export interface WorkspaceResolutionIndex {
  /** Class def `nodeId` → that class's `Scope`. */
  readonly classScopeByDefId: ReadonlyMap<string, Scope>;

  /** Class `Scope.id` → class def `nodeId`. */
  readonly classScopeIdToDefId: ReadonlyMap<ScopeId, string>;

  /** Module scope by file path. */
  readonly moduleScopeByFile: ReadonlyMap<string, Scope>;
}

Sources: gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:1-30

Building the Index

export function buildWorkspaceResolutionIndex(
  parsedFiles: readonly ParsedFile[],
): WorkspaceResolutionIndex {
  const classScopeByDefId = new Map<string, Scope>();
  const classScopeIdToDefId = new Map<ScopeId, string>();
  const moduleScopeByFile = new Map<string, Scope>();

  for (const parsed of parsedFiles) {
    const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
    if (moduleScope !== undefined) moduleScopeByFile.set(parsed.filePath, moduleScope);

    for (const scope of parsed.scopes) {
      if (scope.kind !== 'Class') continue;
      const cd = scope.ownedDefs.find((d) => isClassLike(d.type));
      if (cd !== undefined) {
        classScopeByDefId.set(cd.nodeId, scope);
        classScopeIdToDefId.set(scope.id, cd.nodeId);
      }
    }
  }

  return { classScopeByDefId, classScopeIdToDefId, moduleScopeByFile };
}

Sources: gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:30-55

Language Support

The pipeline supports multiple languages through provider-specific implementations:

PHP Import Resolution

export function resolvePhpImportTargetInternal(
  targetRaw: string,
  _fromFile: string,
  allFilePaths: ReadonlySet<string>,
  resolutionConfig?: unknown,
): string | null

Sources: gitnexus/src/core/ingestion/languages/php/import-target.ts:1-30

C Header Scanning

export function scanHeaderFiles(repoPath: string): ReadonlySet<string> {
  const headers = new Set<string>();
  walk(repoPath, repoPath, headers);
  return headers;
}

Sources: gitnexus/src/core/ingestion/languages/c/header-scan.ts:1-20

C# Import Decomposition

type ImportKind = 'namespace' | 'alias' | 'static';

interface ImportSpec {
  readonly kind: ImportKind;
  readonly source: string;
  readonly name: string;
  readonly alias?: string;
  readonly atNode: SyntaxNode;
}

Sources: gitnexus/src/core/ingestion/languages/csharp/import-decomposer.ts:1-30

Semantic Model Contract

The ParsedFile is the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline. Key invariants:

1. Scope-resolution passes MUST NOT build a parallel parse representation — they should reuse the orchestrator's treeCache
2. Edits from runScopeResolution and the legacy DAG are indistinguishable to downstream consumers
3. Node identity uses the same generateId() helper across both paths

Sources: gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts:1-30

Performance Considerations

Chunked Processing

Files are processed in chunks to maintain responsiveness:

for (let i = 0; i < files.length; i++) {
  const file = files[i];
  onProgress?.(i + 1, files.length);
  if (i % 20 === 0) await yieldToEventLoop();
}

Sources: gitnexus/src/core/ingestion/heritage-processor.ts:10-15

Worker Pool Dispatch

The parsing processor uses a worker pool for parallel file processing:

const chunkResults = await workerPool.dispatch<ParseWorkerInput, ParseWorkerResult>(
  parseableFiles,
  (filesProcessed) => {
    onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
  },
);

Sources: gitnexus/src/core/ingestion/parsing-processor.ts:1-50

Cache Management

ASTs are cached with buffer size optimization for large files:

const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;
tree = parseSourceSafe(parser, parseContent, undefined, {
  bufferSize: getTreeSitterBufferSize(parseContent),
});
astCache.set(file.path, tree);

Configuration

Language Availability

const language = getLanguageFromFilename(file.path);
if (!language) continue;
if (!isLanguageAvailable(language)) {
  if (skippedByLang) {
    skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);
  }
  continue;
}

Tree-sitter Queries

Each language provider supplies tree-sitter queries for extraction:

const provider = getProvider(language);
const queryStr = provider.treeSitterQueries;
if (!queryStr) continue;

Summary

The Indexing Pipeline transforms source code into a queryable graph through:

1. Structure Discovery — File enumeration and classification
2. Parallel Parsing — Tree-sitter AST generation with caching
3. Scope Extraction — Per-file semantic structure extraction
4. Cross-file Resolution — Import and reference resolution
5. Relationship Building — Heritage, calls, and dependencies
6. Index Materialization — Fast lookup indexes for the graph

The pipeline is designed for incremental updates and supports both full repository ingestion and targeted re-indexing of changed files.

Related Pages

Related topics: Indexing Pipeline, Search System

Knowledge Graph

The Knowledge Graph is the core data structure in GitNexus that represents a codebase as an interconnected network of nodes and relationships. It serves as the semantic backbone for code exploration, dependency analysis, and AI-powered queries.

Overview

The Knowledge Graph transforms source code into a queryable graph where:

• Nodes represent code entities (files, functions, classes, interfaces, modules)
• Edges represent relationships (imports, calls, containment, inheritance)

This abstraction enables powerful navigation patterns like tracing execution flows, finding circular dependencies, and identifying highly-connected components.

Sources: gitnexus/src/core/graph/types.ts

Core Architecture

Graph Interface

The KnowledgeGraph interface provides the fundamental operations for building and querying the graph:

interface KnowledgeGraph {
  addNode(node: GraphNode): void;
  addRelationship(relationship: GraphRelationship): void;
  removeNode(nodeId: string): boolean;
  removeNodesByFile(filePath: string): number;
  removeRelationship(relationshipId: string): boolean;
  getNode(id: string): GraphNode | undefined;
  forEachNode(fn: (node: GraphNode) => void): void;
  forEachRelationship(fn: (rel: GraphRelationship) => void): void;
  nodeCount: number;
  relationshipCount: number;
}

Sources: gitnexus/src/core/graph/types.ts

Node Structure

Graph nodes contain:

Sources: gitnexus-shared/src/graph/types.ts

Relationship Structure

Relationships connect nodes with semantic meaning:

interface GraphRelationship {
  id: string;
  type: RelationshipType;
  sourceId: string;
  targetId: string;
  confidence: number;      // 0.0 - 1.0
  reason: string;          // Human-readable explanation
}

Sources: gitnexus-shared/src/graph/types.ts

Node Types

The system recognizes multiple node labels representing different code entities:

Sources: gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts

Relationship Types

Core Relationships

Sources: gitnexus/src/core/ingestion/emit-references.ts

Confidence Scoring

Relationships include a confidence score:

• 1.0 - Resolved reference (fully verified)
• 0.5 - Unresolved reference (symbol not found in index)

graph.addRelationship({
  id: `rel:imports:${scopeId}->${targetModule}:${localName}`,
  sourceId: scopeId,
  targetId: targetModule,
  type: 'IMPORTS',
  confidence: edge.linkStatus === 'unresolved' ? 0.5 : 1,
  reason: `import ${edge.kind} ${edge.localName}`,
});

Sources: gitnexus/src/core/ingestion/emit-references.ts

Build Pipeline

The Knowledge Graph is constructed through a multi-phase pipeline:

graph TD
    A[Source Files] --> B[Structure Processor]
    B --> C[File/Folder Nodes]
    C --> D[Parsing Processor]
    D --> E[Symbol Nodes]
    E --> F[Emit References]
    F --> G[Import Edges]
    G --> H[Wildcard Synthesis]
    H --> I[Final Graph]

Phase 1: Structure Processing

The structure processor creates nodes for the file system hierarchy:

const processStructure = (graph: KnowledgeGraph, paths: string[]) => {
  paths.forEach((path) => {
    const parts = path.split('/');
    let currentPath = '';
    let parentId = '';

    parts.forEach((part, index) => {
      const isFile = index === parts.length - 1;
      const label = isFile ? 'File' : 'Folder';
      currentPath = currentPath ? `${currentPath}/${part}` : part;
      const nodeId = generateId(label, currentPath);
      
      graph.addNode({
        id: nodeId,
        label: label,
        properties: { name: part, filePath: currentPath },
      });

      if (parentId) {
        graph.addRelationship({
          id: generateId('CONTAINS', `${parentId}->${nodeId}`),
          type: 'CONTAINS',
          sourceId: parentId,
          targetId: nodeId,
          confidence: 1.0,
          reason: '',
        });
      }
      parentId = nodeId;
    });
  });
};

Sources: gitnexus/src/core/ingestion/structure-processor.ts

Phase 2: Parsing and Symbol Extraction

The parsing processor extracts code symbols and relationships from source files:

export const mergeChunkResults = (
  graph: KnowledgeGraph,
  symbolTable: SymbolTableWriter,
  chunkResults: readonly ParseWorkerResult[],
): WorkerExtractedData => {
  for (const result of chunkResults) {
    for (const node of result.nodes) {
      graph.addNode({
        id: node.id,
        label: node.label as NodeLabel,
        properties: node.properties,
      });
    }
    for (const rel of result.relationships) {
      graph.addRelationship(rel);
    }
    for (const sym of result.symbols) {
      symbolTable.add(sym.filePath, sym.name, sym.nodeId, sym.type, {
        parameterCount: sym.parameterCount,
        requiredParameterCount: sym.requiredParameterCount,
        parameterTypes: sym.parameterTypes,
        returnType: sym.returnType,
        declaredType: sym.declaredType,
      });
    }
  }
};

Sources: gitnexus/src/core/ingestion/parsing-processor.ts

Phase 3: Reference Emission

References connect code entities across scopes and files:

export interface EmitStats {
  readonly edgesEmitted: number;
  readonly skippedNoCaller: number;        // No caller def resolved
  readonly skippedMissingTarget: number;  // Target not in DefIndex
  readonly scopeNodesEmitted: number;      // Only if INGESTION_EMIT_SCOPES=1
  readonly scopeEdgesEmitted: number;
}

Sources: gitnexus/src/core/ingestion/emit-references.ts

Phase 4: Wildcard Import Synthesis

For languages with whole-module import semantics (Go, Ruby, C/C++, Swift), wildcard imports are expanded into per-symbol bindings:

const IMPORTABLE_SYMBOL_LABELS = new Set([
  'Function', 'Class', 'Interface', 'Struct', 'Enum',
  'Trait', 'TypeAlias', 'Const', 'Static', 'Record',
  'Union', 'Typedef', 'Macro',
]);

/** Max synthetic bindings per importing file — prevents memory bloat */
const MAX_SYNTHETIC_BINDINGS_PER_FILE = 1000;

Sources: gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts

The synthesis process:

1. Collects IMPORTS edges for wildcard languages
2. Retrieves exported symbols per file
3. Creates named import bindings up to the limit

Language-Specific Processors

COBOL Processor

COBOL files undergo specialized processing with unique node types:

// PROGRAM-ID -> Module node
const moduleId = generateId('Module', `${filePath}:${extracted.programName}`);

// SECTIONs -> Namespace nodes
// Paragraphs -> Property nodes
// Data items -> Property nodes
graph.addNode({
  id: moduleId,
  label: 'Module',
  properties: {
    name: extracted.programName,
    filePath,
    language: SupportedLanguages.Cobol,
    isExported: true,
  },
});

Nested programs are linked to their enclosing programs:

const enclosing = extracted.programs.find(
  (p) => p.startLine < prog.startLine &&
         p.endLine > prog.endLine &&
         p.nestingDepth < prog.nestingDepth,
);
const nestedParent = enclosing
  ? programModuleIds.get(enclosing.name.toUpperCase()) ?? moduleId
  : moduleId;

Sources: gitnexus/src/core/ingestion/cobol-processor.ts

Symbol Table Integration

The Knowledge Graph integrates with a symbol table for cross-reference resolution:

symbolTable.add(
  filePath,
  symbolName,
  nodeId,
  symbolType,
  {
    parameterCount: number,
    requiredParameterCount: number,
    parameterTypes: string[],
    returnType: string,
    declaredType: string,
  }
);

Sources: gitnexus/src/core/ingestion/parsing-processor.ts

Query Patterns

The graph supports various query patterns for code exploration:

Web Interface Visualization

The GitNexus web UI visualizes the Knowledge Graph with:

• Node size reflects connection count — larger nodes are depended on by more files
• Edges point from importer to imported
• Click interactions open detail panels showing imports, exports, and reverse dependencies

Sources: gitnexus-web/src/components/HelpPanel.tsx

Configuration

Environment Variables

function isScopeEmissionEnabled(): boolean {
  const TRUTHY = new Set(['true', '1', 'yes']);
  const raw = process.env['INGESTION_EMIT_SCOPES'];
  return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());
}

Sources: gitnexus/src/core/ingestion/emit-references.ts

Summary

The Knowledge Graph is a fundamental abstraction in GitNexus that transforms codebase structure into a queryable graph. By modeling files, symbols, and their relationships with confidence scores, it enables:

• Semantic code navigation
• Dependency analysis
• AI-powered queries over code structure
• Documentation generation

The multi-phase build pipeline progressively enriches the graph from raw file structure through parsing, reference resolution, and language-specific processing to produce a comprehensive semantic model of the codebase.

Related Pages

Related topics: Indexing Pipeline, Knowledge Graph

Search System

GitNexus provides a multi-layered search system that enables users to explore code repositories through various search modalities. The system combines traditional keyword-based search with semantic understanding powered by embeddings, supporting navigation by filename, function name, import path, and natural language queries.

Architecture Overview

The search system in GitNexus follows a hybrid architecture that leverages both classical information retrieval techniques and modern neural embedding approaches. This dual-strategy design allows users to perform fast exact-match searches while also enabling semantic understanding of code relationships.

graph TD
    subgraph "Search Entry Points"
        CMD[⌘K / Ctrl K - Global Search]
        FAB[QueryFAB - Natural Language]
        FILE[FileTreePanel Search]
    end
    
    subgraph "Search Pipeline"
        HY[Hybrid Search Engine]
        BM[BM25 Index]
        FTS[Full-Text Search Index]
        EMB[Embedding Pipeline]
    end
    
    subgraph "Result Handling"
        RES[Results Aggregation]
        HL[Highlight Matching Nodes]
        NAV[Navigate to Graph]
    end
    
    CMD --> HY
    FAB --> HY
    FILE --> BM
    HY --> BM
    HY --> EMB
    HY --> FTS
    BM --> RES
    FTS --> RES
    EMB --> RES
    RES --> HL
    HL --> NAV

Core Components

Sources: gitnexus/src/core/search/hybrid-search.ts gitnexus/src/core/search/bm25-index.ts

Search Modalities

GitNexus supports three distinct search modalities that address different user needs:

1. Global Quick Search (⌘K / Ctrl+K)

The primary search interface is accessible via keyboard shortcut ⌘K on macOS or Ctrl+K on Windows/Linux. This modal provides instant access to search nodes across the entire repository.

Features:

• Search by filename
• Search by function name
• Search by import path
• Live highlighting of matching nodes in the graph
• Fuzzy matching support for typo tolerance

UI Behavior: When activated, the search modal overlays the main interface with a centered input field. Results appear in real-time as the user types, with matches highlighted across the knowledge graph visualization. Sources: gitnexus-web/src/components/HelpPanel.tsx gitnexus-web/src/components/FileTreePanel.tsx

2. Natural Language Query (Nexus AI)

GitNexus integrates an AI-powered search capability that allows users to ask questions in natural language about the codebase. This feature relies on the semantic embedding pipeline.

Example Queries:

• "Which files depend on the auth module?"
• "Find circular dependencies in this repo"
• "What are the most connected components?"
• "Show me all files that import useEffect"

Prerequisites: The repository must be indexed and ready for semantic queries. The system checks for "Semantic Ready" status before allowing natural language queries. Sources: gitnexus-web/src/components/HelpPanel.tsx

3. File Tree Search

A dedicated search interface within the file tree panel allows users to filter and locate specific files in the repository structure. This is particularly useful for large codebases with deep directory hierarchies.

Implementation Details:

<input
  type="text"
  placeholder="Search files..."
  value={searchQuery}
  onChange={(e) => setSearchQuery(e.target.value)}
  className="w-full rounded border border-border-subtle bg-elevated py-1.5 pr-3 pl-8 text-xs text-text-primary placeholder:text-text-muted focus:border-accent focus:outline-none"
/>

Sources: gitnexus-web/src/components/FileTreePanel.tsx

Hybrid Search Engine

The HybridSearchEngine class serves as the central orchestrator for search operations, combining multiple ranking strategies to produce relevant results.

Search Strategy

The hybrid approach combines:

1. BM25 Ranking: Classical TF-IDF variant optimized for keyword matching
2. Full-Text Search (FTS): Structured index for structured queries
3. Embedding Similarity: Vector-based semantic matching

Result Aggregation

Results from multiple search backends are aggregated using a weighted scoring system. The final ranking considers:

• Keyword match score (BM25)
• Semantic similarity score (embeddings)
• Graph position relevance
• Connection count to other nodes

graph LR
    A[User Query] --> B[Query Parser]
    B --> C[BM25 Search]
    B --> D[Embedding Query]
    B --> E[FTS Query]
    C --> F[Score Normalization]
    D --> F
    E --> F
    F --> G[Weighted Aggregation]
    G --> H[Result Ranking]
    H --> I[Graph Highlighting]

Sources: gitnexus/src/core/search/hybrid-search.ts

BM25 Index

The BM25 (Best Matching 25) algorithm provides the foundation for keyword-based search ranking in GitNexus. This classical information retrieval technique offers predictable, fast matching for exact and partial term queries.

Key Features

Index Structure

The BM25 index maintains:

• Inverted index: Maps terms to document positions
• Document statistics: Length, term counts, field weights
• IDF table: Global term importance values

Sources: gitnexus/src/core/search/bm25-index.ts

Full-Text Search Indexes

The FTS (Full-Text Search) subsystem provides structured indexing capabilities for code-specific queries. Unlike BM25 which focuses on term matching, FTS supports phrase queries, proximity searches, and structured field filtering.

Index Types

1. Token Index: Standard word tokenization
2. Code Token Index: Language-aware tokenization preserving syntax
3. Symbol Index: Function/class/variable name index

Query Capabilities

Sources: gitnexus/src/core/search/fts-indexes.ts

Embedding Pipeline

The embedding pipeline transforms code entities into dense vector representations that capture semantic meaning. This enables similarity-based search and natural language understanding.

graph TD
    subgraph "Embedding Pipeline"
        SRC[Source Code] --> PRE[Preprocessor]
        PRE --> TOK[Tokenization]
        TOK --> ENC[Encoder Model]
        ENC --> VEC[Vector Output]
    end
    
    subgraph "Storage"
        VEC --> ANN[Approximate NN Index]
        VEC --> DIM[Dimension Reduction]
    end
    
    subgraph "Query Flow"
        Q[Query Text] --> QENC[Query Encoder]
        QENC --> DIST[Distance Calculation]
        ANN --> DIST
        DIST --> TOP[Top-K Results]
    end

WebGPU Acceleration

Embedding generation is computationally intensive. GitNexus leverages WebGPU for GPU-accelerated embedding computation when available. If WebGPU is not supported, the system falls back to CPU-based computation with a warning about reduced performance.

Performance Characteristics:

• WebGPU: Real-time embedding generation
• CPU: Batch processing with estimated completion time
• Memory: Handles large codebases with streaming processing

Sources: gitnexus/src/core/embeddings/embedding-pipeline.ts gitnexus-web/src/components/WebGPUFallbackDialog.tsx

Model Configuration

The embedding pipeline supports configurable embedding models. Users can select from available models in the settings panel or specify custom model identifiers.

Configuration Options:

Sources: gitnexus-web/src/components/SettingsPanel.tsx

Query Interface (QueryFAB)

The QueryFAB (Floating Action Button) component provides persistent access to the natural language query interface. It appears as a floating button in the UI and expands to reveal the query input.

Features

• Natural language query input
• Real-time result preview
• Execution time display
• Result count indicators
• Query result highlighting on graph
• Clear highlight functionality

Result Display

<div className="flex items-center gap-3 text-xs">
  <span className="text-text-secondary">
    <span className="font-semibold text-cyan-400">{queryResult.rows.length}</span> rows
  </span>
  {queryResult.nodeIds.length > 0 && (
    <span className="text-text-secondary">
      <span className="font-semibold text-cyan-400">{queryResult.nodeIds.length}</span> highlighted
    </span>
  )}
  <span className="text-text-muted">{queryResult.executionTime.toFixed(1)}ms</span>
</div>

Result Metrics:

Sources: gitnexus-web/src/components/QueryFAB.tsx

Graph Integration

The search system is tightly integrated with the knowledge graph visualization. Search results directly influence the graph display:

Highlighting

Matching nodes are highlighted in the graph with visual indicators:

• Primary matches: Full opacity, accent color border
• Secondary matches: Reduced opacity, subtle highlight
• Related nodes: Connected nodes shown with edge highlighting

Navigation

Clicking a search result navigates the graph to focus on the corresponding node, opening the detail panel with:

• Imports and exports
• Reverse dependencies
• Node metadata
• Code preview (where applicable)

Keyboard Navigation

Sources: gitnexus-web/src/components/HelpPanel.tsx

Performance Considerations

Index Build Time

Initial index construction scales with repository size:

Query Latency

Optimization Strategies

1. Incremental indexing: Only re-index changed files
2. Query caching: Cache recent semantic query results
3. Approximate nearest neighbor: Trade accuracy for speed in embedding search
4. Streaming processing: Handle large files without memory overflow

Configuration

Server Settings

The search system can be configured through the settings panel:

interface SearchConfig {
  // BM25 parameters
  k1: number;        // Term frequency saturation
  b: number;         // Document length normalization
  
  // Embedding settings
  modelId: string;   // Embedding model
  device: 'webgpu' | 'cpu';
  
  // FTS settings
  analyzer: 'standard' | 'code';
  minTokenLength: number;
}

Ollama Integration

For self-hosted embedding models, GitNexus supports integration with Ollama:

const checkOllamaStatus = async (baseUrl: string): Promise<{
  ok: boolean;
  error: string | null;
}> => {
  const response = await fetch(`${baseUrl}/api/tags`, {
    method: 'GET',
    headers: { 'Content-Type': 'application/json' }
  });
  // ...
};

Sources: gitnexus-web/src/components/SettingsPanel.tsx

Summary

The GitNexus Search System provides a comprehensive, multi-layered approach to code exploration:

1. Fast keyword search via BM25 and FTS indexes for exact matching
2. Semantic understanding through embedding-based similarity
3. Natural language queries powered by AI integration
4. Deep graph integration for visual exploration of search results

The hybrid architecture ensures that users can find exactly what they're looking for through traditional search while also discovering unexpected relationships through semantic queries.

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: Bug: Local path analysis not working in Docker version - always throws "path must be an absolute path" error

• Severity: high
• Finding: Installation risk is backed by a source signal: Bug: Local path analysis not working in Docker version - always throws "path must be an absolute path" error. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1518

2. Installation risk: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…

• Severity: high
• Finding: Installation risk is backed by a source signal: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1444

3. Installation risk: MCP error with Claude: Failed to reconnect to gitnexus: -32000

• Severity: high
• Finding: Installation risk is backed by a source signal: MCP error with Claude: Failed to reconnect to gitnexus: -32000. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1683

4. Installation risk: Unable to install GitNexus in Mac

• Severity: high
• Finding: Installation risk is backed by a source signal: Unable to install GitNexus in Mac. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1164

5. Installation risk: Windows + Node v24.14.0: [email protected] analyze crashes at LadybugDB persist (60%)

• Severity: high
• Finding: Installation risk is backed by a source signal: Windows + Node v24.14.0: [email protected] analyze crashes at LadybugDB persist (60%). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1674

6. Installation risk: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules

• Severity: high
• Finding: Installation risk is backed by a source signal: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1680

7. Installation risk: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension r…

• Severity: high
• Finding: Installation risk is backed by a source signal: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension r…. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1472

8. Configuration risk: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.

• Severity: high
• Finding: Configuration risk is backed by a source signal: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1611

9. Configuration risk: analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments

• Severity: high
• Finding: Configuration risk is backed by a source signal: analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1542

10. Security or permission risk: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present bina…

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present bina…. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/abhigyanpatwari/GitNexus/issues/1690

11. Installation risk: Developers should check this installation risk before relying on the project: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing
• User impact: Developers may fail before the first successful local run: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing. Context: Observed when using windows
• Evidence: failure_mode_cluster:github_issue | fmev_1438bc0fa83941fc6074de2c5412cd25 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing

12. Installation risk: Developers should check this installation risk before relying on the project: MCP error with Claude: Failed to reconnect to gitnexus: -32000

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: MCP error with Claude: Failed to reconnect to gitnexus: -32000
• User impact: Developers may fail before the first successful local run: MCP error with Claude: Failed to reconnect to gitnexus: -32000
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: MCP error with Claude: Failed to reconnect to gitnexus: -32000. Context: Observed when using node, windows
• Evidence: failure_mode_cluster:github_issue | fmev_ebb5d6efaf48e8d879678b8a170aacf8 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000

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.

• MCP error with Claude: Failed to reconnect to gitnexus: -32000 - github / github_issue
• [[Bug] Incorrect edge relationships when duplicate package, class, and me](https://github.com/abhigyanpatwari/GitNexus/issues/1680) - github / github_issue
• WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently - github / github_issue
• GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ - github / github_issue
• Windows + Node v24.14.0: [email protected] analyze crashes at LadybugDB per - github / github_issue
• Windows: FTS skip-guard too aggressive when extension is locally install - github / github_issue
• GitNexus Enterprise for open source - github / github_issue
• bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_ - github / github_issue
• cpp SFINAE: expand type_traits predicate registry (Tier A) - github / github_issue
• Bug: Local path analysis not working in Docker version - always throws "path must be an absolute path" error - GitHub / issue
• Unable to install GitNexus in Mac - GitHub / issue
• Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type. - GitHub / issue