8000 GitHub - woaini731234/GitNexus: my GitNexus, forked from https://github.com/abhigyanpatwari/GitNexus · GitHub
[go: up one dir, main page]

Skip to content
woaini731234Public
forked from chengjon/GitNexus

About

my GitNexus, forked from https://github.com/abhigyanpatwari/GitNexus

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

GitNexus

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

abhigyanpatwari%2FGitNexus | Trendshift

Join the official Discord to discuss ideas, issues etc!

Discord npm version License: PolyForm Noncommercial

Building nervous system for agent context.

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

Gitnexus_CLI.1.mp4

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

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


Recent Major Updates

GitNexus has gone through several substantial upgrade waves recently. The current state is materially stronger in runtime stability, MCP reliability, and codebase architecture than the earlier 1.4-era baseline.

1. Native Runtime and Test-Foundation Stabilization

  • Introduced a centralized native runtime manager for Kuzu / embedder lifecycle policy
  • Split unit vs integration Vitest configs so native suites run under explicit constraints
  • Improved doctor diagnostics to surface runtime and language-support status
  • Reduced reliance on broad native-error suppression in tests and CI

2. LocalBackend Handler-First Refactor

  • Broke up the old monolithic gitnexus/src/mcp/local/local-backend.ts
  • Added explicit seams:
    • runtime/ for repo discovery + Kuzu lifecycle
    • tools/handlers/ for tool behavior
    • tools/shared/ for query safety and formatting helpers
    • tool-context / tool-registry for dispatch
  • Extracted handlers for:
    • query
    • cypher
    • context
    • overview
    • impact
    • detect_changes
    • rename

This refactor was not only structural: it also added regression coverage and several correctness hardening passes while the code was being split.

3. detect_changes Worktree-Aware Git Resolution

  • detect_changes now supports an explicit cwd parameter
  • The tool now reports richer path metadata, including which path was actually used for git diff
  • Fallback reasons are explicit, so worktree ambiguity is diagnosable instead of silent
  • Worktree limitations are now surfaced in output instead of being buried as implicit behavior

4. Safer MCP and Refactor Workflows

  • gitnexus analyze now auto-stops local gitnexus mcp holders that are blocking .gitnexus/kuzu
  • MCP lifecycle handling was improved to reduce orphaned local MCP processes on client disconnect
  • Rename flow was hardened:
    • better path-traversal handling
    • clearer warning surfaces when text-search coverage is skipped
    • stronger preview/apply consistency
    • less optimistic confidence labeling
  • Cypher formatting and validation were hardened so malformed inputs and table-breaking output are handled more safely

5. Embeddings Ergonomics

  • Embeddings config can be stored in ~/.gitnexus/config.json
  • Added gitnexus config embeddings show|set|clear
  • Improved local Ollama workflow guidance and embedding progress visibility

If you are upgrading from an older checkout, the most important practical difference is this:

  • the MCP/CLI surface is more explicit and diagnosable
  • local indexing/runtime behavior is more stable
  • large internal MCP codepaths are now easier to change safely
  • detect_changes and rename are safer to trust in real development workflows

Star History

Star History Chart

Two Ways to Use GitNexus

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

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


CLI + MCP (recommended)

The CLI indexes your repository and runs an MCP server that gives AI agents deep codebase awareness.

Quick Start

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

That remains the main indexing command. By default it also refreshes AGENTS.md / CLAUDE.md, installs repo-local skills, updates .gitignore, and registers the repo for multi-repo MCP discovery.

To configure MCP for your editor, run npx gitnexus setup once — or set it up manually below.

Use npx gitnexus init-project when you only want project-local scaffolding (.gitignore, AGENTS.md, CLAUDE.md, repo skills) without a full re-index. Use npx gitnexus refresh-context when the index is already present and you only want to regenerate context files from current metadata. After global setup, npx gitnexus doctor --host <name> checks whether host config, registry entries, and repo indexing are all ready.

AI-Readable Quick Start

For AI CLIs or local agents on this machine, prefer the linked local command instead of npx:

Canonical single-file reference: docs/ai-cli-local-quick-start.md

# 0. Optional: verify that the local fork is active
which gitnexus
gitnexus --version

# 1. Build first if you changed local GitNexus source under gitnexus/src
cd /opt/claude/GitNexus/gitnexus
npm run build

# 2. In the target repository root
cd /path/to/repo
gitnexus analyze

# Expected outputs:
# - .gitnexus/
# - AGENTS.md
# - CLAUDE.md
# - .claude/skills/gitnexus/

# 3. Verify host wiring
gitnexus doctor --host codex
gitnexus doctor --host claude

# 4. Context-only workflows
gitnexus init-project
gitnexus refresh-context

# 5. Start MCP manually if a host needs a direct stdio command
gitnexus mcp

If gitnexus is not on PATH, use the local build directly:

node /opt/claude/GitNexus/gitnexus/dist/cli/index.js analyze
node /opt/claude/GitNexus/gitnexus/dist/cli/index.js doctor --host codex
node /opt/claude/GitNexus/gitnexus/dist/cli/index.js mcp

MCP Setup

gitnexus setup auto-detects your editors and writes the correct global MCP config. You only need to run it once.

Editor Support

Editor MCP Skills Hooks (auto-augment) Support
Claude Code Yes Yes Yes (PreToolUse + PostToolUse) Full
Cursor Yes Yes — MCP + Skills
Windsurf Yes — — MCP
OpenCode Yes Yes — MCP + Skills

Claude Code gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that auto-reindex after commits.

Community Integrations

Agent Install Source
pi pi install npm:pi-gitnexus pi-gitnexus

If you prefer manual configuration:

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

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

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

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

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

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

CLI Commands

gitnexus setup                    # Configure MCP for your editors (one-time)
gitnexus doctor --host codex      # Verify host MCP readiness and repo/index state
gitnexus analyze [path]           # Index a repository (default: also register + gitignore + context refresh)
gitnexus analyze --force          # Force full re-index
gitnexus analyze --skills         # Generate repo-specific skill files from detected communities
gitnexus analyze --no-context     # Index only, skip AGENTS.md / CLAUDE.md refresh
gitnexus analyze --no-gitignore   # Index only, skip .gitignore update
gitnexus analyze --no-register    # Index only, skip global registry update
gitnexus analyze --embeddings     # Enable embedding generation for semantic search
gitnexus analyze --verbose        # Log skipped files when parsers are unavailable
gitnexus config embeddings show   # Show stored/effective embeddings config
gitnexus config embeddings set    # Persist embeddings config to ~/.gitnexus/config.json
gitnexus config embeddings clear  # Remove only embeddings settings from ~/.gitnexus/config.json
gitnexus init-project [path]      # Initialize .gitignore, AGENTS.md / CLAUDE.md, and repo skills
gitnexus refresh-context [path]   # Regenerate AGENTS.md / CLAUDE.md and repo skills only
gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
gitnexus list                    # List all indexed repositories
gitnexus status                  # Show index status for current repo
gitnexus clean                   # Delete index for current repo
gitnexus clean --all --force     # Delete all indexes
gitnexus wiki [path]             # Generate repository wiki from knowledge graph
gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
gitnexus wiki --base-url <url>   # Wiki with custom LLM API base URL

Embeddings Configuration

Use plain gitnexus analyze when you want the fastest refresh and exact symbol, file, or keyword search is enough.

Graph tools, BM25/FTS search, impact analysis, and context lookups still work without embeddings.

Use gitnexus analyze --embeddings when natural-language, concept, or fuzzy code search matters.

This enables hybrid retrieval (BM25 + semantic + RRF) but takes longer and requires an embedding provider such as Ollama or Hugging Face.

During gitnexus analyze, GitNexus will automatically detect and stop local gitnexus mcp processes that are holding the target repo's .gitnexus/kuzu file open. This avoids the common KuzuDB lock conflict when you have multiple CLI/editor sessions open.

For normal refreshes, prefer gitnexus analyze --embeddings without --force so GitNexus can reuse existing embeddings.

For a local Ollama GPU setup, start with batchSize=64; if you want a more conservative baseline, try 32.

You can configure embeddings once in ~/.gitnexus/config.json instead of exporting shell variables every run:

{
  "embeddings": {
    "provider": "ollama",
    "ollamaBaseUrl": "http://localhost:11434",
    "ollamaModel": "qwen3-embedding:0.6b",
    "nodeLimit": 90000,
    "batchSize": 64
  }
}

CLI helpers:

gitnexus config embeddings show
gitnexus config embeddings set --provider ollama --ollama-base-url http://localhost:11434 --ollama-model qwen3-embedding:0.6b --node-limit 90000 --batch-size 64
gitnexus config embeddings clear

Environment variables still take precedence over ~/.gitnexus/config.json.

What Your AI Agent Gets

7 tools exposed via MCP:

Tool What It Does repo Param
list_repos Discover all indexed repositories —
query Process-grouped hybrid search (BM25 + semantic + RRF) Optional
context 360-degree symbol view — categorized refs, process participation Optional
impact Blast radius analysis with depth grouping and confidence Optional
detect_changes Git-diff impact — maps changed lines to affected processes Optional
rename Multi-file coordinated rename with graph + text search Optional
cypher Raw Cypher graph queries Optional

When only one repo is indexed, the repo parameter is optional. With multiple repos, specify which one: query({query: "auth", repo: "my-app"}).

Resources for instant context:

Resource Purpose
gitnexus://repos List all indexed repositories (read this first)
gitnexus://repo/{name}/context Codebase stats, staleness check, and available tools
gitnexus://repo/{name}/clusters All functional clusters with cohesion scores
gitnexus://repo/{name}/cluster/{name} Cluster members and details
gitnexus://repo/{name}/processes All execution flows
gitnexus://repo/{name}/process/{name} Full process trace with steps
gitnexus://repo/{name}/schema Graph schema for Cypher queries

2 MCP prompts for guided workflows:

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

4 agent skills installed to .claude/skills/ automatically:

  • Exploring — Navigate unfamiliar code using the knowledge graph
  • Debugging — Trace bugs through call chains
  • Impact Analysis — Analyze blast radius before changes
  • Refactoring — Plan safe refactors using dependency mapping

Repo-specific skills generated with --skills:

When you run gitnexus analyze --skills, GitNexus detects the functional areas of your codebase (via Leiden community detection) and generates a SKILL.md file for each one under .claude/skills/generated/. Each skill describes a module's key files, entry points, execution flows, and cross-area connections — so your AI agent gets targeted context for the exact area of code you're working in. Skills are regenerated on each --skills run to stay current with the codebase.

Installed automatically by gitnexus analyze, gitnexus init-project, and gitnexus refresh-context for repo-local usage, plus gitnexus setup for supported global integrations.


Multi-Repo MCP Architecture

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

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

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

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

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

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

How it works: Each gitnexus analyze stores the index in .gitnexus/ inside the repo (portable, gitignored) and registers a pointer in ~/.gitnexus/registry.json. When an AI agent starts, the MCP server reads the registry and can serve any indexed repo. KuzuDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). During re-indexing, gitnexus analyze writes a short-lived reindexing.lock file and proactively quiesces local gitnexus mcp holders for that repo before reopening Kuzu in write mode. If only one repo is indexed, the repo parameter is optional on all tools — agents don't need to change anything.

gitnexus setup and the host adapters own global editor/MCP configuration. gitnexus doctor is the matching diagnostics layer for that global setup. gitnexus init-project and gitnexus refresh-context only touch project-local files inside the target repository.


Web UI (browser-based)

A fully client-side graph explorer and AI chat. No server, no install — your code never leaves the browser.

Try it now: gitnexus.vercel.app — drag & drop a ZIP and start exploring.

gitnexus_img

Or run locally:

git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus/gitnexus-web
npm install
npm run dev

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

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


The Problem GitNexus Solves

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

What happens:

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

Traditional Graph RAG vs GitNexus

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

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

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

Core innovation: Precomputed Relational Intelligence

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

How It Works

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

  1. Structure — Walks the file tree and maps folder/file relationships
  2. Parsing — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
  3. Resolution — Resolves imports and function calls across files with language-aware logic
  4. Clustering — Groups related symbols into functional communities
  5. Processes — Traces execution flows from entry points through call chains
  6. Search — Builds hybrid search indexes for fast retrieval

Supported Languages

TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust, PHP, Swift


Tool Examples

Impact Analysis

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

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

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

Options: maxDepth, minConfidence, relationTypes (CALLS, IMPORTS, EXTENDS, IMPLEMENTS), includeTests

Process-Grouped Search

query({query: "authentication middleware"})

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

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

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

Context (360-degree Symbol View)

context({name: "validateUser"})

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

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

outgoing:
  calls: [checkPassword, createSession]

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

Detect Changes (Pre-Commit)

detect_changes({scope: "all"})

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

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

Rename (Multi-File)

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

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

Cypher Queries

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

Wiki Generation

Generate LLM-powered documentation from your knowledge graph:

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

# Use a custom model or provider
gitnexus wiki --model gpt-4o
gitnexus wiki --base-url https://api.anthropic.com/v1

# Force full regeneration
gitnexus wiki --force

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


Tech Stack

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

Roadmap

Actively Building

  • LLM Cluster Enrichment — Semantic cluster names via LLM API
  • AST Decorator Detection — Parse @Controller, @Get, etc.
  • Incremental Indexing — Only re-index changed files

Recently Completed

  • Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
  • Process-Grouped Search, 360-Degree Context, Claude Code Hooks
  • Multi-Repo MCP, Zero-Config Setup, 11 Language Support
  • Community Detection, Process Detection, Confidence Scoring
  • Hybrid Search, Vector Index

Security & Privacy

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

Acknowledgments

About

my GitNexus, forked from https://github.com/abhigyanpatwari/GitNexus

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0