Repository: abhigyanpatwari/GitNexus

Stars: 27832

.cursorrules

Deprecated for Cursor Agent Mode

Use .cursor/index.mdc (alwaysApply: true) for project rules. See AGENTS.md.

This file is kept only as a breadcrumb for older workflows.

CLAUDE.md

Last reviewed: 2026-04-13

Project: GitNexus · Environment: dev · Maintainer: repository maintainers (see GitHub)

Follow AGENTS.md for the canonical rules; this file adds Claude Code–specific deltas. Cursor-specific notes live only in AGENTS.md.

Scope

See the Scope table in AGENTS.md for read/write/execute/off-limits boundaries. Cursor-specific workflow notes also live only in AGENTS.md.

Model Configuration

- Primary: Pin per Claude Code / Anthropic org policy (explicit model id). Do not rely on an unversioned latest alias for governed workflows.
- Fallback: As configured in Claude Code (organization default or user override).
- Notes: The GitNexus CLI analyzer does not call an LLM.

Execution Sequence (complex tasks)

Same discipline as AGENTS.md: before large multi-step work, state which AGENTS.md / GUARDRAILS.md rules apply, current Scope, and planned validation commands (npm test, tsc, etc.). When pausing, summarize progress in the chat or a local scratch file (do not add HANDOFF.md to the repo), then /clear and resume with that summary.

Claude Code hooks

Prefer PreToolUse hooks for hard gates (e.g. tests before git_commit). Adapt hook commands to gitnexus/ npm scripts.

Context budget

If always-on instructions grow, load deep conventions via conditional reads (e.g. “When writing new code, read STANDARDS.md”) instead of pasting long blocks here. In Cursor, prefer .cursor/index.mdc plus optional .cursor/rules/*.mdc globs (see AGENTS.md § Context budget).

Reference Documentation

- This repository: AGENTS.md (Cursor + monorepo notes), ARCHITECTURE.md, CONTRIBUTING.md, GUARDRAILS.md.
- GitNexus: .claude/skills/gitnexus/; MCP and indexed-repo rules live only in AGENTS.md (gitnexus:start … gitnexus:end). See GitNexus rules below.

Changelog

| Date | Version | Change |
|------|---------|--------|
| 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. |
| 2026-03-24 | 1.2.0 | Removed duplicated gitnexus:start block and scope table; replaced with pointers to AGENTS.md. |
| 2026-03-23 | 1.1.0 | Updated agent instructions to match AGENTS.md. |
| 2026-03-22 | 1.0.0 | Added structured header and changelog. |

---

GitNexus rules

GitNexus MCP rules are in the 

`GitNexus — Code Intelligence`

This project is indexed by GitNexus as GitNexus (4325 symbols, 10556 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

If any GitNexus tool warns the index is stale, run npx gitnexus analyze in terminal first.

`Always Do`

- MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run gitnexus_impact({target: "symbolName", direction: "upstream"})and report the blast radius (direct callers, affected processes, risk level) to the user. - MUST rungitnexus_detect_changes() before committingto verify your changes only affect expected symbols and execution flows. - MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits. - When exploring unfamiliar code, usegitnexus_query({query: "concept"})to find execution flows instead of grepping. It returns process-grouped results ranked by relevance. - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — usegitnexus_context({name: "symbolName"}).

`When Debugging`

1. gitnexus_query({query: "<error or symptom>"})— find execution flows related to the issue 2.gitnexus_context({name: "<suspect function>"})— see all callers, callees, and process participation 3.READ gitnexus://repo/GitNexus/process/{processName}— trace the full execution flow step by step 4. For regressions:gitnexus_detect_changes({scope: "compare", base_ref: "main"}) — see what your branch changed

`When Refactoring`

- Renaming: MUST use gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true}) first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with dry_run: false. - Extracting/Splitting: MUST rungitnexus_context({name: "target"}) to see all incoming/outgoing refs, then gitnexus_impact({target: "target", direction: "upstream"})to find all external callers before moving code. - After any refactor: rungitnexus_detect_changes({scope: "all"}) to verify only expected files changed.

`Never Do`

- NEVER edit a function, class, or method without first running gitnexus_impacton it. - NEVER ignore HIGH or CRITICAL risk warnings from impact analysis. - NEVER rename symbols with find-and-replace — usegitnexus_renamewhich understands the call graph. - NEVER commit changes without runninggitnexus_detect_changes() to check affected scope.

`Tools Quick Reference`

| Tool | When to use | Command | |------|-------------|---------| |query | Find code by concept | gitnexus_query({query: "auth validation"})| |context | 360-degree view of one symbol | gitnexus_context({name: "validateUser"})| |impact | Blast radius before editing | gitnexus_impact({target: "X", direction: "upstream"})| |detect_changes | Pre-commit scope check | gitnexus_detect_changes({scope: "staged"})| |rename | Safe multi-file rename | gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})| |cypher | Custom graph queries | gitnexus_cypher({query: "MATCH ..."}) |

`Impact Risk Levels`

| Depth | Meaning | Action | |-------|---------|--------| | d=1 | WILL BREAK — direct callers/importers | MUST update these | | d=2 | LIKELY AFFECTED — indirect deps | Should test | | d=3 | MAY NEED TESTING — transitive | Test if critical path |

`Resources`

| Resource | Use for | |----------|---------| |gitnexus://repo/GitNexus/context| Codebase overview, check index freshness | |gitnexus://repo/GitNexus/clusters| All functional areas | |gitnexus://repo/GitNexus/processes| All execution flows | |gitnexus://repo/GitNexus/process/{name} | Step-by-step execution trace |

`Self-Check Before Finishing`

Before completing any code modification task, verify: 1.gitnexus_impactwas run for all modified symbols 2. No HIGH/CRITICAL risk warnings were ignored 3.gitnexus_detect_changes()confirms changes match expected scope 4. All d=1 (WILL BREAK) dependents were updated

`Keeping the Index Fresh`

After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:

bash

npx gitnexus analyze

If the index previously included embeddings, preserve them by adding --embeddings:

bash

npx gitnexus analyze --embeddings

To check whether embeddings exist, inspect .gitnexus/meta.json — the stats.embeddings field shows the count (0 means no embeddings). Running analyze without --embeddings will delete any previously generated embeddings.

Claude Code users: A PostToolUse hook handles this automatically after git commit and git merge.

`CLI`

| Task | Read this skill file | |------|---------------------| | Understand architecture / "How does X work?" |.claude/skills/gitnexus/gitnexus-exploring/SKILL.md| | Blast radius / "What breaks if I change X?" |.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md| | Trace bugs / "Why is X failing?" |.claude/skills/gitnexus/gitnexus-debugging/SKILL.md| | Rename / extract / split / refactor |.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md| | Tools, resources, schema reference |.claude/skills/gitnexus/gitnexus-guide/SKILL.md| | Index, status, clean, wiki CLI commands |.claude/skills/gitnexus/gitnexus-cli/SKILL.md |

 block in AGENTS.md — load that section when working with MCP tools or the graph index.

GitNexus — Code Intelligence

This project is indexed by GitNexus as GitNexus (3298 symbols, 7954 relationships, 185 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

If any GitNexus tool warns the index is stale, run npx gitnexus analyze in terminal first.

Always Do

- MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run gitnexus_impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
- MUST run gitnexus_detect_changes() before committing to verify your changes only affect expected symbols and execution flows.
- MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
- When exploring unfamiliar code, use gitnexus_query({query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use gitnexus_context({name: "symbolName"}).

When Debugging

1. gitnexus_query({query: "<error or symptom>"}) — find execution flows related to the issue
2. gitnexus_context({name: "<suspect function>"}) — see all callers, callees, and process participation
3. READ gitnexus://repo/GitNexus/process/{processName} — trace the full execution flow step by step
4. For regressions: gitnexus_detect_changes({scope: "compare", base_ref: "main"}) — see what your branch changed

When Refactoring

- Renaming: MUST use gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true}) first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with dry_run: false.
- Extracting/Splitting: MUST run gitnexus_context({name: "target"}) to see all incoming/outgoing refs, then gitnexus_impact({target: "target", direction: "upstream"}) to find all external callers before moving code.
- After any refactor: run gitnexus_detect_changes({scope: "all"}) to verify only expected files changed.

Never Do

- NEVER edit a function, class, or method without first running gitnexus_impact on it.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
- NEVER rename symbols with find-and-replace — use gitnexus_rename which understands the call graph.
- NEVER commit changes without running gitnexus_detect_changes() to check affected scope.

Tools Quick Reference

| Tool | When to use | Command |
|------|-------------|---------|
| query | Find code by concept | gitnexus_query({query: "auth validation"}) |
| context | 360-degree view of one symbol | gitnexus_context({name: "validateUser"}) |
| impact | Blast radius before editing | gitnexus_impact({target: "X", direction: "upstream"}) |
| detect_changes | Pre-commit scope check | gitnexus_detect_changes({scope: "staged"}) |
| rename | Safe multi-file rename | gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true}) |
| cypher | Custom graph queries | gitnexus_cypher({query: "MATCH ..."}) |

Impact Risk Levels

| Depth | Meaning | Action |
|-------|---------|--------|
| d=1 | WILL BREAK — direct callers/importers | MUST update these |
| d=2 | LIKELY AFFECTED — indirect deps | Should test |
| d=3 | MAY NEED TESTING — transitive | Test if critical path |

Resources

| Resource | Use for |
|----------|---------|
| gitnexus://repo/GitNexus/context | Codebase overview, check index freshness |
| gitnexus://repo/GitNexus/clusters | All functional areas |
| gitnexus://repo/GitNexus/processes | All execution flows |
| gitnexus://repo/GitNexus/process/{name} | Step-by-step execution trace |

Self-Check Before Finishing

Before completing any code modification task, verify:
1. gitnexus_impact was run for all modified symbols
2. No HIGH/CRITICAL risk warnings were ignored
3. gitnexus_detect_changes() confirms changes match expected scope
4. All d=1 (WILL BREAK) dependents were updated

Keeping the Index Fresh

After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:

bash

npx gitnexus analyze

If the index previously included embeddings, preserve them by adding --embeddings:

bash

npx gitnexus analyze --embeddings

To check whether embeddings exist, inspect .gitnexus/meta.json — the stats.embeddings field shows the count (0 means no embeddings). Running analyze without --embeddings will delete any previously generated embeddings.

Claude Code users: A PostToolUse hook handles this automatically after git commit and git merge.

CLI

| Task | Read this skill file |
|------|---------------------|
| Understand architecture / "How does X work?" | .claude/skills/gitnexus/gitnexus-exploring/SKILL.md |
| Blast radius / "What breaks if I change X?" | .claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md |
| Trace bugs / "Why is X failing?" | .claude/skills/gitnexus/gitnexus-debugging/SKILL.md |
| Rename / extract / split / refactor | .claude/skills/gitnexus/gitnexus-refactoring/SKILL.md |
| Tools, resources, schema reference | .claude/skills/gitnexus/gitnexus-guide/SKILL.md |
| Index, status, clean, wiki CLI commands | .claude/skills/gitnexus/gitnexus-cli/SKILL.md |

README.md

GitNexus

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

<h2>Join the official Discord to discuss ideas, issues etc!</h2>

<p><strong>Enterprise (SaaS & Self-hosted)</strong> - <a href="https://akonlabs.com">akonlabs.com</a></p>

</div>

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.

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

Like DeepWiki, but deeper. DeepWiki helps you understand code. GitNexus lets you analyze it — 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, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with goliath models.

---

Star History

![Star History Chart](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left)

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, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis |
| Scale | Full repos, any size | Limited by browser memory (~5k files), or unlimited via backend mode |
| Install | npm install -g gitnexus | No install — gitnexus.vercel.app |
| Storage | LadybugDB native (fast, persistent) | LadybugDB WASM (in-memory, per session) |
| Parsing | Tree-sitter native bindings | Tree-sitter WASM |
| Privacy | Everything local, no network | Everything in-browser, no server |

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

---

Enterprise

GitNexus is available as an enterprise offering - either as a fully managed SaaS or a self-hosted deployment. Also available for commercial use of the OSS version with proper licensing.

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

Upcoming:
- Auto regression forensics
- End-to-end test generation

👉 Learn more at akonlabs.com

💬 For commercial licensing or enterprise inquiries, ping us on Discord or drop an email at [email protected]

---

Development

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

CLI + MCP (recommended)

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

Quick Start

bash

Index your repo (run from repo root)

npx gitnexus 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.

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

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

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

| Project | Author | Description |
|---------|--------|-------------|
| pi-gitnexus | @tintinweb | GitNexus plugin for pi — pi install npm:pi-gitnexus |
| gitnexus-stable-ops | @ShunsukeHayashi | Stable ops & deployment workflows (Miyabi ecosystem) |

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

If you prefer manual configuration:

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

bash

macOS / Linux

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

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

Codex (full support — MCP + skills):

bash

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

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

json

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

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

json

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

Codex (~/.codex/config.toml for system scope, or .codex/config.toml for project scope):

toml

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

CLI Commands

bash

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 --skills        # Generate repo-specific skill files from detected communities
gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
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 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
Repository groups (multi-repo / monorepo service tracking)

gitnexus group create <name>     # Create a repository group
gitnexus group add <name> <repo> # Add a repo to a group
gitnexus group remove <name> <repo> # Remove a repo from a group
gitnexus group list [name]       # List groups, or show one group's config
gitnexus group sync <name>       # Extract contracts and match across repos/services
gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
gitnexus group query <name> <q>  # Search execution flows across all repos in a group
gitnexus group status <name>     # Check staleness of repos in a group

What Your AI Agent Gets

16 tools exposed via MCP (11 per-repo + 5 group):

| 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 |
| group_list | List configured repository groups | — |
| group_sync | Extract contracts and match across repos/services | — |
| group_contracts| Inspect extracted contracts and cross-links | — |
| group_query | Search execution flows across all repos in a group | — |
| group_status | Check staleness of repos in a group | — |

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.

---

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.

mermaid

flowchart TD
    subgraph CLI [CLI Commands]
        Setup["gitnexus setup"]
        Analyze["gitnexus analyze"]
        Clean["gitnexus clean"]
        List["gitnexus list"]
    end
    subgraph Registry ["~/.gitnexus/"]
        RegFile["registry.json"]
    end
    subgraph Repos [Project Repos]
        RepoA[".gitnexus/ in repo A"]
        RepoB[".gitnexus/ in repo B"]
    end
    subgraph MCP [MCP Server]
        Server["server.ts"]
        Backend["LocalBackend"]
        Pool["Connection Pool"]
        ConnA["LadybugDB conn A"]
        ConnB["LadybugDB conn B"]
    end    Setup -->|"writes global MCP config"| CursorConfig["~/.cursor/mcp.json"]
    Analyze -->|"registers repo"| RegFile
    Analyze -->|"stores index"| RepoA
    Clean -->|"unregisters repo"| RegFile
    List -->|"reads"| RegFile
    Server -->|"reads registry"| RegFile
    Server --> Backend
    Backend --> Pool
    Pool -->|"lazy open"| ConnA
    Pool -->|"lazy open"| ConnB
    ConnA -->|"queries"| RepoA
    ConnB -->|"queries"| RepoB

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. LadybugDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). If only one repo is indexed, the repo parameter is optional on all tools — agents don't need to change anything.

---

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.

Or run locally:

bash

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

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

Local Backend Mode: Run gitnexus serve and open the web UI 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, Codex, 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:

mermaid

flowchart TB
    subgraph Traditional["Traditional Graph RAG"]
        direction TB
        U1["User: What depends on UserService?"]
        U1 --> LLM1["LLM receives raw graph"]
        LLM1 --> Q1["Query 1: Find callers"]
        Q1 --> Q2["Query 2: What files?"]
        Q2 --> Q3["Query 3: Filter tests?"]
        Q3 --> Q4["Query 4: High-risk?"]
        Q4 --> OUT1["Answer after 4+ queries"]
    end    subgraph GN["GitNexus Smart Tools"]
        direction TB
        U2["User: What depends on UserService?"]
        U2 --> TOOL["impact UserService upstream"]
        TOOL --> PRECOMP["Pre-structured response:
        8 callers, 3 clusters, all 90%+ confidence"]
        PRECOMP --> OUT2["Complete answer, 1 query"]
    end

Core innovation: Precomputed Relational Intelligence

- Reliability — 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, function calls, heritage, constructor inference, and self/this receiver types 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

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

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

---

Tool Examples

Impact Analysis

text

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

text

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)

text

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)

text

detect_changes({scope: "all"})
summary:
  changed_count: 12
  affected_count: 3
  changed_files: 4
  risk_level: mediumchanged_symbols: [validateUser, AuthService, ...]
affected_processes: [LoginFlow, RegistrationFlow, ...]

Rename (Multi-File)

text

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

cypher

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

bash

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 | LadybugDB native | LadybugDB WASM |
| Embeddings | HuggingFace transformers.js (GPU/CPU) | transformers.js (WebGPU/WASM) |
| Search | BM25 + semantic + RRF | BM25 + semantic + RRF |
| Agent Interface | MCP (stdio) | LangChain ReAct agent |
| Visualization | — | Sigma.js + Graphology (WebGL) |
| Frontend | — | React 18, TypeScript, Vite, Tailwind v4 |
| Clustering | Graphology | Graphology |
| Concurrency | Worker threads + async | Web Workers + Comlink |

---

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

- [X] Constructor-Inferred Type Resolution, self/this Receiver Mapping
- [X] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
- [X] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
- [X] Multi-Repo MCP, Zero-Config Setup, 14 Language Support
- [X] Community Detection, Process Detection, Confidence Scoring
- [X] 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

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

Repository: abhigyanpatwari/GitNexus

Stars: 27832

.cursorrules Copy Chapter

Deprecated for Cursor Agent Mode

CLAUDE.md Copy Chapter

Scope Copy Chapter

Model Configuration Copy Chapter

Execution Sequence (complex tasks) Copy Chapter

Claude Code hooks Copy Chapter

Context budget Copy Chapter

Reference Documentation Copy Chapter

Changelog Copy Chapter

GitNexus rules Copy Chapter

GitNexus — Code Intelligence

Always Do Copy Chapter

When Debugging Copy Chapter

When Refactoring Copy Chapter

Never Do Copy Chapter

Tools Quick Reference Copy Chapter

Impact Risk Levels Copy Chapter

Resources Copy Chapter

Self-Check Before Finishing Copy Chapter

Keeping the Index Fresh Copy Chapter

CLI Copy Chapter

GitNexus — Code Intelligence

Always Do Copy Chapter

When Debugging Copy Chapter

When Refactoring Copy Chapter

Never Do Copy Chapter

Tools Quick Reference Copy Chapter

Impact Risk Levels Copy Chapter

Resources Copy Chapter

Self-Check Before Finishing Copy Chapter

Keeping the Index Fresh Copy Chapter

CLI Copy Chapter

README.md Copy Chapter

GitNexus

Star History Copy Chapter

Two Ways to Use GitNexus Copy Chapter

Enterprise Copy Chapter

Development Copy Chapter

CLI + MCP (recommended) Copy Chapter

Quick Start Copy Section

Index your repo (run from repo root)

MCP Setup Copy Section

Editor Support Copy Section

Community Integrations Copy Chapter

macOS / Linux

Windows

CLI Commands Copy Section

Repository groups (multi-repo / monorepo service tracking)

What Your AI Agent Gets Copy Section

Multi-Repo MCP Architecture Copy Chapter

Web UI (browser-based) Copy Chapter

The Problem GitNexus Solves Copy Chapter

Traditional Graph RAG vs GitNexus Copy Section

How It Works Copy Chapter

Supported Languages Copy Section

Tool Examples Copy Chapter

Impact Analysis Copy Section

Process-Grouped Search Copy Section

Context (360-degree Symbol View) Copy Section

Detect Changes (Pre-Commit) Copy Section

Rename (Multi-File) Copy Section

Cypher Queries Copy Section

Wiki Generation Copy Chapter

Requires an LLM API key (OPENAI_API_KEY, etc.)

Use a custom model or provider

Force full regeneration

Tech Stack Copy Chapter

Roadmap Copy Chapter

Actively Building Copy Section

Recently Completed Copy Section

Security & Privacy Copy Chapter

Acknowledgments Copy Chapter

.cursorrules

CLAUDE.md

Scope

Model Configuration

Execution Sequence (complex tasks)

Claude Code hooks

Context budget

Reference Documentation

Changelog

GitNexus rules

`GitNexus — Code Intelligence`

`Always Do`

`When Debugging`

`When Refactoring`

`Never Do`

`Tools Quick Reference`

`Impact Risk Levels`

`Resources`

`Self-Check Before Finishing`

`Keeping the Index Fresh`

`CLI`

Always Do

When Debugging

When Refactoring

Never Do

Tools Quick Reference

Impact Risk Levels

Resources

Self-Check Before Finishing

Keeping the Index Fresh

CLI

README.md

Star History

Two Ways to Use GitNexus

Enterprise

Development

CLI + MCP (recommended)

Quick Start

MCP Setup

Editor Support

Community Integrations

CLI Commands

What Your AI Agent Gets

Multi-Repo MCP Architecture

Web UI (browser-based)

The Problem GitNexus Solves

Traditional Graph RAG vs GitNexus

How It Works

Supported Languages

Tool Examples

Impact Analysis

Process-Grouped Search

Context (360-degree Symbol View)

Detect Changes (Pre-Commit)

Rename (Multi-File)

Cypher Queries

Wiki Generation

Tech Stack

Roadmap

Actively Building

Recently Completed

Security & Privacy

Acknowledgments