GitNexus

A Sipher-maintained npm distribution of GitNexus.

Graph-powered code intelligence for AI agents. Index any codebase into a knowledge graph, then query it via MCP or CLI.

Works with Cursor, Claude Code, Windsurf, Cline, OpenCode, and any MCP-compatible tool.

Why?

AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by precomputing every dependency, call chain, and relationship into a queryable graph.

Three commands to give your AI agent full codebase awareness.

Quick Start

# Run once without installing globally
npx @duytransipher/gitnexus@latest analyze

That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates AGENTS.md / CLAUDE.md context files — all in one command.

Install globally if you want the persistent gitnexus CLI:

npm install -g @duytransipher/gitnexus

To configure MCP for your editor, run npx @duytransipher/gitnexus@latest setup once — or set it up manually below. After a global install, the executable name stays gitnexus.

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) | 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 automatically enrich grep/glob/bash calls with knowledge graph context.

Community Integrations

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

MCP Setup (manual)

If you prefer to configure manually instead of using gitnexus setup:

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

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

Cursor / Windsurf

Add to ~/.cursor/mcp.json (global — works for all projects):

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

OpenCode

Add to ~/.config/opencode/config.json:

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

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

The result is a LadybugDB graph database stored locally in .gitnexus/ with full-text search and semantic embeddings.

MCP Tools

Your AI agent gets these tools automatically:

| 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 | | sync_unreal_asset_manifest | Refresh Unreal Blueprint manifest via the configured Unreal commandlet | Optional | | find_native_blueprint_references | Confirm direct Blueprint references to a native C++ function | Optional | | expand_blueprint_chain | Expand upstream/downstream Blueprint graph flow from a confirmed anchor | Optional | | find_blueprints_derived_from_native_class | List Blueprint assets derived from a native class via the manifest | Optional |

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

MCP Resources

| Resource | Purpose | |----------|---------| | gitnexus://repos | List all indexed repositories (read 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 |

MCP Prompts

| 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 |

CLI Commands

gitnexus setup                    # Configure MCP for your editors (one-time)
gitnexus analyze [path]           # Index a repository (or update stale index)
gitnexus analyze --force          # Force full re-index
gitnexus analyze --embeddings     # Enable embedding generation (slower, better search)
gitnexus analyze --verbose        # Log skipped files when parsers are unavailable
gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
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 LLM-powered docs from knowledge graph
gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
gitnexus sipher-patched [path]   # Validate S2 repo shape and Sipher gateway env
gitnexus unreal-sync             # Refresh Unreal Blueprint asset manifest for the current indexed repo
gitnexus unreal-find-refs <fn>   # Confirm Blueprint references to a native C++ function
gitnexus unreal-expand-chain ... # Expand a Blueprint graph chain from a confirmed anchor
gitnexus unreal-derived-blueprints <class> # List Blueprints derived from a native class

Unreal Blueprint References

GitNexus can bridge into an Unreal Editor commandlet to answer "which Blueprints call this native C++ function?" with graph-confirmed results.

1. Install the plugin from ../gitnexus-unreal/ into your Unreal project's Plugins/ folder.
2. Create .gitnexus/unreal/config.json in the indexed repo:

{
  "editor_cmd": "C:/Program Files/Epic Games/UE_5.5/Engine/Binaries/Win64/UnrealEditor-Cmd.exe",
  "project_path": "D:/Projects/sipher_test_project/sipher_test_project.uproject",
  "commandlet": "GitNexusBlueprintAnalyzer",
  "timeout_ms": 300000
}

From this source repo, you can do both with:

pwsh -File .\gitnexus\scripts\setup-unreal-gitnexus.ps1 -ProjectRoot D:\Projects\git_nexus_ue_lyra

The script fails if the plugin or config already exists unless you pass -Force.

3. Refresh the manifest with gitnexus unreal-sync.
4. Query references with gitnexus unreal-find-refs "AMyActor::MyBlueprintCallableFunction".

The manifest lives at .gitnexus/unreal/asset-manifest.json. GitNexus uses it only as a candidate shortlist; confirmed graph references still come from the Unreal commandlet.

Multi-Repo Support

GitNexus supports indexing multiple repositories. Each gitnexus analyze registers the repo in a global registry (~/.gitnexus/registry.json). The MCP server serves all indexed repos automatically.

Supported Languages

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

Language Feature Matrix

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

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

Agent Skills

GitNexus ships with skill files that teach AI agents how to use the tools effectively:

• 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

Installed automatically by both gitnexus analyze (per-repo) and gitnexus setup (global).

Requirements

• Node.js >= 18
• Git repository (uses git for commit tracking)

Privacy

• All processing happens locally on your machine
• No code is sent to any server
• Index stored in .gitnexus/ inside your repo (gitignored)
• Global registry at ~/.gitnexus/ stores only paths and metadata

Web UI

GitNexus also has a browser-based UI at gitnexus.vercel.app — 100% client-side, your code never leaves the browser.

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.

License

PolyForm Noncommercial 1.0.0

Free for non-commercial use. Contact for commercial licensing.