# Repository: abhigyanpatwari/GitNexus # Stars: 27832 ## .cursorrules # Deprecated for Cursor Agent Mode Use **`.cursor/index.mdc`** (`alwaysApply: true`) for project rules. See [AGENTS.md](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](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](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](AGENTS.md) § Context budget). ## Reference Documentation - **This repository:** [AGENTS.md](AGENTS.md) (Cursor + monorepo notes), [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md), [GUARDRAILS.md](GUARDRAILS.md). - **GitNexus:** `.claude/skills/gitnexus/`; MCP and indexed-repo rules live only in [AGENTS.md](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 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: ""})` — find execution flows related to the issue 2. `gitnexus_context({name: ""})` — 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` | ` block in **[AGENTS.md](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: ""})` — find execution flows related to the issue 2. `gitnexus_context({name: ""})` — 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.
abhigyanpatwari%2FGitNexus | Trendshift

Join the official Discord to discuss ideas, issues etc!

Discord npm version License: PolyForm Noncommercial

Enterprise (SaaS & Self-hosted) - akonlabs.com

**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://api.star-history.com/svg?repos=abhigyanpatwari/GitNexus&type=date&legend=top-left)](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](https://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](https://akonlabs.com) 💬 For commercial licensing or enterprise inquiries, ping us on [Discord](https://discord.gg/AAsRVT6fGb) or drop an email at founders@akonlabs.com --- ## Development - [ARCHITECTURE.md](ARCHITECTURE.md) — packages, index → graph → MCP flow, where to change code - [RUNBOOK.md](RUNBOOK.md) — analyze, embeddings, stale index, MCP recovery, CI snippets - [GUARDRAILS.md](GUARDRAILS.md) — safety rules and operational “Signs” for contributors and agents - [CONTRIBUTING.md](CONTRIBUTING.md) — license, setup, commits, and pull requests - [TESTING.md](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](https://github.com/tintinweb/pi-gitnexus) | [@tintinweb](https://github.com/tintinweb) | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` | | [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/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 # Wiki with custom LLM model (default: gpt-4o-mini) gitnexus wiki --base-url # Wiki with custom LLM API base URL # Repository groups (multi-repo / monorepo service tracking) gitnexus group create # Create a repository group gitnexus group add # Add a repo to a group gitnexus group remove # Remove a repo from a group gitnexus group list [name] # List groups, or show one group's config gitnexus group sync # Extract contracts and match across repos/services gitnexus group contracts # Inspect extracted contracts and cross-links gitnexus group query # Search execution flows across all repos in a group gitnexus group status # 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](https://gitnexus.vercel.app) — drag & drop a ZIP and start exploring. gitnexus_img 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 ``` 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 ```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](https://tree-sitter.github.io/) — AST parsing - [LadybugDB](https://ladybugdb.com/) — Embedded graph database with vector support (formerly KuzuDB) - [Sigma.js](https://www.sigmajs.org/) — WebGL graph rendering - [transformers.js](https://huggingface.co/docs/transformers.js) — Browser ML - [Graphology](https://graphology.github.io/) — Graph data structures - [MCP](https://modelcontextprotocol.io/) — Model Context Protocol