USP

GitNexus builds a comprehensive knowledge graph, tracking every code relationship for deep analysis, unlike tools focused on descriptions. It provides AI agents with full architectural clarity, making them perform comparably to Goliath mod…

Use cases

• 01Exploring unfamiliar codebases
• 02Debugging errors and tracing execution flows
• 03Performing impact analysis before code changes
• 04Refactoring and restructuring code
• 05Generating auto-updating code wikis

Detected files (8)

• .claude/skills/gitnexus/gitnexus-exploring/SKILL.mdskill
  Show content (3037 bytes)

  ---
  name: gitnexus-exploring
  description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
  ---
  
  # Exploring Codebases with GitNexus
  
  ## When to Use
  
  - "How does authentication work?"
  - "What's the project structure?"
  - "Show me the main components"
  - "Where is the database logic?"
  - Understanding code you haven't seen before
  
  ## Workflow
  
  ```
  1. READ gitnexus://repos                          → Discover indexed repos
  2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
  3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
  4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
  5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
  ```
  
  > If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
  
  ## Checklist
  
  ```
  - [ ] READ gitnexus://repo/{name}/context
  - [ ] gitnexus_query for the concept you want to understand
  - [ ] Review returned processes (execution flows)
  - [ ] gitnexus_context on key symbols for callers/callees
  - [ ] READ process resource for full execution traces
  - [ ] Read source files for implementation details
  ```
  
  ## Resources
  
  | Resource                                | What you get                                            |
  | --------------------------------------- | ------------------------------------------------------- |
  | `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
  | `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
  | `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
  | `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
  
  ## Tools
  
  **gitnexus_query** — find execution flows related to a concept:
  
  ```
  gitnexus_query({query: "payment processing"})
  → Processes: CheckoutFlow, RefundFlow, WebhookHandler
  → Symbols grouped by flow with file locations
  ```
  
  **gitnexus_context** — 360-degree view of a symbol:
  
  ```
  gitnexus_context({name: "validateUser"})
  → Incoming calls: loginHandler, apiMiddleware
  → Outgoing calls: checkToken, getUserById
  → Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
  ```
  
  ## Example: "How does payment processing work?"
  
  ```
  1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
  2. gitnexus_query({query: "payment processing"})
     → CheckoutFlow: processPayment → validateCard → chargeStripe
     → RefundFlow: initiateRefund → calculateRefund → processRefund
  3. gitnexus_context({name: "processPayment"})
     → Incoming: checkoutHandler, webhookHandler
     → Outgoing: validateCard, chargeStripe, saveTransaction
  4. Read src/payments/processor.ts for implementation details
  ```
  

• .claude/skills/gitnexus/gitnexus-debugging/SKILL.mdskill
  Show content (3164 bytes)

  ---
  name: gitnexus-debugging
  description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
  ---
  
  # Debugging with GitNexus
  
  ## When to Use
  
  - "Why is this function failing?"
  - "Trace where this error comes from"
  - "Who calls this method?"
  - "This endpoint returns 500"
  - Investigating bugs, errors, or unexpected behavior
  
  ## Workflow
  
  ```
  1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
  2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
  3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
  4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
  ```
  
  > If "Index is stale" → run `npx gitnexus analyze` in terminal.
  
  ## Checklist
  
  ```
  - [ ] Understand the symptom (error message, unexpected behavior)
  - [ ] gitnexus_query for error text or related code
  - [ ] Identify the suspect function from returned processes
  - [ ] gitnexus_context to see callers and callees
  - [ ] Trace execution flow via process resource if applicable
  - [ ] gitnexus_cypher for custom call chain traces if needed
  - [ ] Read source files to confirm root cause
  ```
  
  ## Debugging Patterns
  
  | Symptom              | GitNexus Approach                                          |
  | -------------------- | ---------------------------------------------------------- |
  | Error message        | `gitnexus_query` for error text → `context` on throw sites |
  | Wrong return value   | `context` on the function → trace callees for data flow    |
  | Intermittent failure | `context` → look for external calls, async deps            |
  | Performance issue    | `context` → find symbols with many callers (hot paths)     |
  | Recent regression    | `detect_changes` to see what your changes affect           |
  
  ## Tools
  
  **gitnexus_query** — find code related to error:
  
  ```
  gitnexus_query({query: "payment validation error"})
  → Processes: CheckoutFlow, ErrorHandling
  → Symbols: validatePayment, handlePaymentError, PaymentException
  ```
  
  **gitnexus_context** — full context for a suspect:
  
  ```
  gitnexus_context({name: "validatePayment"})
  → Incoming calls: processCheckout, webhookHandler
  → Outgoing calls: verifyCard, fetchRates (external API!)
  → Processes: CheckoutFlow (step 3/7)
  ```
  
  **gitnexus_cypher** — custom call chain traces:
  
  ```cypher
  MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
  RETURN [n IN nodes(path) | n.name] AS chain
  ```
  
  ## Example: "Payment endpoint returns 500 intermittently"
  
  ```
  1. gitnexus_query({query: "payment error handling"})
     → Processes: CheckoutFlow, ErrorHandling
     → Symbols: validatePayment, handlePaymentError
  
  2. gitnexus_context({name: "validatePayment"})
     → Outgoing calls: verifyCard, fetchRates (external API!)
  
  3. READ gitnexus://repo/my-app/process/CheckoutFlow
     → Step 3: validatePayment → calls fetchRates (external)
  
  4. Root cause: fetchRates calls external API without proper timeout
  ```
  

• .claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.mdskill
  Show content (2919 bytes)

  ---
  name: gitnexus-impact-analysis
  description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
  ---
  
  # Impact Analysis with GitNexus
  
  ## When to Use
  
  - "Is it safe to change this function?"
  - "What will break if I modify X?"
  - "Show me the blast radius"
  - "Who uses this code?"
  - Before making non-trivial code changes
  - Before committing — to understand what your changes affect
  
  ## Workflow
  
  ```
  1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
  2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
  3. gitnexus_detect_changes()                               → Map current git changes to affected flows
  4. Assess risk and report to user
  ```
  
  > If "Index is stale" → run `npx gitnexus analyze` in terminal.
  
  ## Checklist
  
  ```
  - [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
  - [ ] Review d=1 items first (these WILL BREAK)
  - [ ] Check high-confidence (>0.8) dependencies
  - [ ] READ processes to check affected execution flows
  - [ ] gitnexus_detect_changes() for pre-commit check
  - [ ] Assess risk level and report to user
  ```
  
  ## Understanding Output
  
  | Depth | Risk Level       | Meaning                  |
  | ----- | ---------------- | ------------------------ |
  | d=1   | **WILL BREAK**   | Direct callers/importers |
  | d=2   | LIKELY AFFECTED  | Indirect dependencies    |
  | d=3   | MAY NEED TESTING | Transitive effects       |
  
  ## Risk Assessment
  
  | Affected                       | Risk     |
  | ------------------------------ | -------- |
  | <5 symbols, few processes      | LOW      |
  | 5-15 symbols, 2-5 processes    | MEDIUM   |
  | >15 symbols or many processes  | HIGH     |
  | Critical path (auth, payments) | CRITICAL |
  
  ## Tools
  
  **gitnexus_impact** — the primary tool for symbol blast radius:
  
  ```
  gitnexus_impact({
    target: "validateUser",
    direction: "upstream",
    minConfidence: 0.8,
    maxDepth: 3
  })
  
  → d=1 (WILL BREAK):
    - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
    - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
  
  → d=2 (LIKELY AFFECTED):
    - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
  ```
  
  **gitnexus_detect_changes** — git-diff based impact analysis:
  
  ```
  gitnexus_detect_changes({scope: "staged"})
  
  → Changed: 5 symbols in 3 files
  → Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
  → Risk: MEDIUM
  ```
  
  ## Example: "What breaks if I change validateUser?"
  
  ```
  1. gitnexus_impact({target: "validateUser", direction: "upstream"})
     → d=1: loginHandler, apiMiddleware (WILL BREAK)
     → d=2: authRouter, sessionManager (LIKELY AFFECTED)
  
  2. READ gitnexus://repo/my-app/processes
     → LoginFlow and TokenRefresh touch validateUser
  
  3. Risk: 2 direct callers, 2 processes = MEDIUM
  ```
  

• .claude/skills/gitnexus/gitnexus-cli/SKILL.mdskill
  Show content (3859 bytes)

  ---
  name: gitnexus-cli
  description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
  ---
  
  # GitNexus CLI Commands
  
  All commands work via `npx` — no global install required.
  
  ## Commands
  
  ### analyze — Build or refresh the index
  
  ```bash
  npx gitnexus analyze
  ```
  
  Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
  
  | Flag                | Effect                                                                                                  |
  | ------------------- | ------------------------------------------------------------------------------------------------------- |
  | `--force`           | Force full re-index even if up to date                                                                  |
  | `--embeddings`      | Enable embedding generation for semantic search (off by default)                                        |
  | `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them.    |
  
  **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
  
  ### status — Check index freshness
  
  ```bash
  npx gitnexus status
  ```
  
  Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
  
  ### clean — Delete the index
  
  ```bash
  npx gitnexus clean
  ```
  
  Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
  
  | Flag      | Effect                                            |
  | --------- | ------------------------------------------------- |
  | `--force` | Skip confirmation prompt                          |
  | `--all`   | Clean all indexed repos, not just the current one |
  
  ### wiki — Generate documentation from the graph
  
  ```bash
  npx gitnexus wiki
  ```
  
  Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
  
  | Flag                | Effect                                    |
  | ------------------- | ----------------------------------------- |
  | `--force`           | Force full regeneration                   |
  | `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
  | `--base-url <url>`  | LLM API base URL                          |
  | `--api-key <key>`   | LLM API key                               |
  | `--concurrency <n>` | Parallel LLM calls (default: 3)           |
  | `--gist`            | Publish wiki as a public GitHub Gist      |
  
  ### list — Show all indexed repos
  
  ```bash
  npx gitnexus list
  ```
  
  Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
  
  ## After Indexing
  
  1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
  2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
  
  ## Troubleshooting
  
  - **"Not inside a git repository"**: Run from a directory inside a git repo
  - **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
  - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
  

• .claude/skills/gitnexus/gitnexus-guide/SKILL.mdskill
  Show content (3480 bytes)

  ---
  name: gitnexus-guide
  description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
  ---
  
  # GitNexus Guide
  
  Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
  
  ## Always Start Here
  
  For any task involving code understanding, debugging, impact analysis, or refactoring:
  
  1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
  2. **Match your task to a skill below** and **read that skill file**
  3. **Follow the skill's workflow and checklist**
  
  > If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
  
  ## Skills
  
  | Task                                         | Skill to read       |
  | -------------------------------------------- | ------------------- |
  | Understand architecture / "How does X work?" | `gitnexus-exploring`         |
  | Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
  | Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
  | Rename / extract / split / refactor          | `gitnexus-refactoring`       |
  | Tools, resources, schema reference           | `gitnexus-guide` (this file) |
  | Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
  
  ## Tools Reference
  
  | Tool             | What it gives you                                                        |
  | ---------------- | ------------------------------------------------------------------------ |
  | `query`          | Process-grouped code intelligence — execution flows related to a concept |
  | `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
  | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
  | `detect_changes` | Git-diff impact — what do your current changes affect                    |
  | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
  | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
  | `list_repos`     | Discover indexed repos                                                   |
  
  ## Resources Reference
  
  Lightweight reads (~100-500 tokens) for navigation:
  
  | Resource                                       | Content                                   |
  | ---------------------------------------------- | ----------------------------------------- |
  | `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
  | `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
  | `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
  | `gitnexus://repo/{name}/processes`             | All execution flows                       |
  | `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
  | `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
  
  ## Graph Schema
  
  **Nodes:** File, Function, Class, Interface, Method, Community, Process
  **Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
  
  ```cypher
  MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
  RETURN caller.name, caller.filePath
  ```
  

• .claude/skills/gitnexus/gitnexus-pr-review/SKILL.mdskill
  Show content (5429 bytes)

  ---
  name: gitnexus-pr-review
  description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\""
  ---
  
  # PR Review with GitNexus
  
  ## When to Use
  
  - "Review this PR"
  - "What does PR #42 change?"
  - "Is this safe to merge?"
  - "What's the blast radius of this PR?"
  - "Are there missing tests for this PR?"
  - Reviewing someone else's code changes before merge
  
  ## Workflow
  
  ```
  1. gh pr diff <number>                                    → Get the raw diff
  2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
  3. For each changed symbol:
     gitnexus_impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
  4. gitnexus_context({name: "<key symbol>"})               → Understand callers/callees
  5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
  6. Summarize findings with risk assessment
  ```
  
  > If "Index is stale" → run `npx gitnexus analyze` in terminal before reviewing.
  
  ## Checklist
  
  ```
  - [ ] Fetch PR diff (gh pr diff or git diff base...head)
  - [ ] gitnexus_detect_changes to map changes to affected execution flows
  - [ ] gitnexus_impact on each non-trivial changed symbol
  - [ ] Review d=1 items (WILL BREAK) — are callers updated?
  - [ ] gitnexus_context on key changed symbols to understand full picture
  - [ ] Check if affected processes have test coverage
  - [ ] Assess overall risk level
  - [ ] Write review summary with findings
  ```
  
  ## Review Dimensions
  
  | Dimension | How GitNexus Helps |
  | --- | --- |
  | **Correctness** | `context` shows callers — are they all compatible with the change? |
  | **Blast radius** | `impact` shows d=1/d=2/d=3 dependents — anything missed? |
  | **Completeness** | `detect_changes` shows all affected flows — are they all handled? |
  | **Test coverage** | `impact({includeTests: true})` shows which tests touch changed code |
  | **Breaking changes** | d=1 upstream items that aren't updated in the PR = potential breakage |
  
  ## Risk Assessment
  
  | Signal | Risk |
  | --- | --- |
  | Changes touch <3 symbols, 0-1 processes | LOW |
  | Changes touch 3-10 symbols, 2-5 processes | MEDIUM |
  | Changes touch >10 symbols or many processes | HIGH |
  | Changes touch auth, payments, or data integrity code | CRITICAL |
  | d=1 callers exist outside the PR diff | Potential breakage — flag it |
  
  ## Tools
  
  **gitnexus_detect_changes** — map PR diff to affected execution flows:
  
  ```
  gitnexus_detect_changes({scope: "compare", base_ref: "main"})
  
  → Changed: 8 symbols in 4 files
  → Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
  → Risk: MEDIUM
  ```
  
  **gitnexus_impact** — blast radius per changed symbol:
  
  ```
  gitnexus_impact({target: "validatePayment", direction: "upstream"})
  
  → d=1 (WILL BREAK):
    - processCheckout (src/checkout.ts:42) [CALLS, 100%]
    - webhookHandler (src/webhooks.ts:15) [CALLS, 100%]
  
  → d=2 (LIKELY AFFECTED):
    - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
  ```
  
  **gitnexus_impact with tests** — check test coverage:
  
  ```
  gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})
  
  → Tests that cover this symbol:
    - validatePayment.test.ts [direct]
    - checkout.integration.test.ts [via processCheckout]
  ```
  
  **gitnexus_context** — understand a changed symbol's role:
  
  ```
  gitnexus_context({name: "validatePayment"})
  
  → Incoming calls: processCheckout, webhookHandler
  → Outgoing calls: verifyCard, fetchRates
  → Processes: CheckoutFlow (step 3/7), RefundFlow (step 1/5)
  ```
  
  ## Example: "Review PR #42"
  
  ```
  1. gh pr diff 42 > /tmp/pr42.diff
     → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
  
  2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
     → Changed symbols: validatePayment, PaymentInput, formatAmount
     → Affected processes: CheckoutFlow, RefundFlow
     → Risk: MEDIUM
  
  3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
     → d=1: processCheckout, webhookHandler (WILL BREAK)
     → webhookHandler is NOT in the PR diff — potential breakage!
  
  4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
     → d=1: validatePayment (in PR), createPayment (NOT in PR)
     → createPayment uses the old PaymentInput shape — breaking change!
  
  5. gitnexus_context({name: "formatAmount"})
     → Called by 12 functions — but change is backwards-compatible (added optional param)
  
  6. Review summary:
     - MEDIUM risk — 3 changed symbols affect 2 execution flows
     - BUG: webhookHandler calls validatePayment but isn't updated for new signature
     - BUG: createPayment depends on PaymentInput type which changed
     - OK: formatAmount change is backwards-compatible
     - Tests: checkout.test.ts covers processCheckout path, but no webhook test
  ```
  
  ## Review Output Format
  
  Structure your review as:
  
  ```markdown
  ## PR Review: <title>
  
  **Risk: LOW / MEDIUM / HIGH / CRITICAL**
  
  ### Changes Summary
  - <N> symbols changed across <M> files
  - <P> execution flows affected
  
  ### Findings
  1. **[severity]** Description of finding
     - Evidence from GitNexus tools
     - Affected callers/flows
  
  ### Missing Coverage
  - Callers not updated in PR: ...
  - Untested flows: ...
  
  ### Recommendation
  APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
  ```
  

• .claude/skills/gitnexus/gitnexus-refactoring/SKILL.mdskill
  Show content (4107 bytes)

  ---
  name: gitnexus-refactoring
  description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
  ---
  
  # Refactoring with GitNexus
  
  ## When to Use
  
  - "Rename this function safely"
  - "Extract this into a module"
  - "Split this service"
  - "Move this to a new file"
  - Any task involving renaming, extracting, splitting, or restructuring code
  
  ## Workflow
  
  ```
  1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
  2. gitnexus_query({query: "X"})                            → Find execution flows involving X
  3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
  4. Plan update order: interfaces → implementations → callers → tests
  ```
  
  > If "Index is stale" → run `npx gitnexus analyze` in terminal.
  
  ## Checklists
  
  ### Rename Symbol
  
  ```
  - [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
  - [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
  - [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
  - [ ] gitnexus_detect_changes() — verify only expected files changed
  - [ ] Run tests for affected processes
  ```
  
  ### Extract Module
  
  ```
  - [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
  - [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
  - [ ] Define new module interface
  - [ ] Extract code, update imports
  - [ ] gitnexus_detect_changes() — verify affected scope
  - [ ] Run tests for affected processes
  ```
  
  ### Split Function/Service
  
  ```
  - [ ] gitnexus_context({name: target}) — understand all callees
  - [ ] Group callees by responsibility
  - [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
  - [ ] Create new functions/services
  - [ ] Update callers
  - [ ] gitnexus_detect_changes() — verify affected scope
  - [ ] Run tests for affected processes
  ```
  
  ## Tools
  
  **gitnexus_rename** — automated multi-file rename:
  
  ```
  gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
  → 12 edits across 8 files
  → 10 graph edits (high confidence), 2 ast_search edits (review)
  → Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
  ```
  
  **gitnexus_impact** — map all dependents first:
  
  ```
  gitnexus_impact({target: "validateUser", direction: "upstream"})
  → d=1: loginHandler, apiMiddleware, testUtils
  → Affected Processes: LoginFlow, TokenRefresh
  ```
  
  **gitnexus_detect_changes** — verify your changes after refactoring:
  
  ```
  gitnexus_detect_changes({scope: "all"})
  → Changed: 8 files, 12 symbols
  → Affected processes: LoginFlow, TokenRefresh
  → Risk: MEDIUM
  ```
  
  **gitnexus_cypher** — custom reference queries:
  
  ```cypher
  MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
  RETURN caller.name, caller.filePath ORDER BY caller.filePath
  ```
  
  ## Risk Rules
  
  | Risk Factor         | Mitigation                                |
  | ------------------- | ----------------------------------------- |
  | Many callers (>5)   | Use gitnexus_rename for automated updates |
  | Cross-area refs     | Use detect_changes after to verify scope  |
  | String/dynamic refs | gitnexus_query to find them               |
  | External/public API | Version and deprecate properly            |
  
  ## Example: Rename `validateUser` to `authenticateUser`
  
  ```
  1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
     → 12 edits: 10 graph (safe), 2 ast_search (review)
     → Files: validator.ts, login.ts, middleware.ts, config.json...
  
  2. Review ast_search edits (config.json: dynamic reference!)
  
  3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
     → Applied 12 edits across 8 files
  
  4. gitnexus_detect_changes({scope: "all"})
     → Affected: LoginFlow, TokenRefresh
     → Risk: MEDIUM — run tests for these flows
  ```
  

• .claude-plugin/marketplace.jsonmarketplace
  Show content (609 bytes)

  {
    "name": "gitnexus-marketplace",
    "owner": {
      "name": "GitNexus",
      "email": "nico@gitnexus.dev"
    },
    "metadata": {
      "description": "Code intelligence powered by a knowledge graph — execution flows, blast radius, and semantic search",
      "homepage": "https://github.com/nicosxt/gitnexus"
    },
    "plugins": [
      {
        "name": "gitnexus",
        "version": "1.3.3",
        "source": "./gitnexus-claude-plugin",
        "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase."
      }
    ]
  }
  

README

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.

Join the official Discord to discuss ideas, issues etc!

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

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 founders@akonlabs.com

---

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

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

Faster install (no C++ toolchain needed): set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 before npm install -g gitnexus to skip the native tree-sitter-dart and tree-sitter-proto builds. Dart/Proto files won't be parsed, but install completes in seconds without python3/make/g++. Strict =1 only — any other value falls through to the rebuild.

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 detect a stale index after commits and prompt the agent to reindex.

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:

Recommended for fastest startup: install gitnexus globally (npm i -g gitnexus) and run gitnexus setup — this writes an absolute-path MCP config that bypasses npx entirely. The pinned-npx snippets below are a quickstart fallback; on a cold cache the npx install can exceed Claude Code's MCP_TIMEOUT default (~30s).

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

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

codex 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": {
      "type": "local",
      "command": ["gitnexus", "mcp"]
    }
  }
}

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

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

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 --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 --skip-git        # Index folders that are not Git repositories
gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
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 <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `gitnexus list`)
gitnexus group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
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

If analyze reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use gitnexus analyze --worker-timeout 60 or set GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000. For very large files, GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES controls the worker job byte budget.

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.

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 client-side graph explorer and AI chat — your code never leaves your machine.

Try it now: gitnexus.vercel.app — run npx gitnexus@latest serve locally and the page auto-connects to your local backend.

Or run the frontend locally:

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
# Then in another terminal, start the backend the frontend connects to:
npx gitnexus@latest serve

Docker

The official Docker setup ships two signed images orchestrated by docker-compose.yaml. Each image is published to both GitHub Container Registry (GHCR) and Docker Hub — same build, same digest, same Cosign signature — so pick whichever registry you prefer:

Purpose	GHCR (default in docker-compose.yaml)	Docker Hub mirror
CLI / gitnexus serve backend (HTTP API on port 4747, MCP, indexer)	ghcr.io/abhigyanpatwari/gitnexus:latest	akonlabs/gitnexus:latest
Static web UI (port 4173)	ghcr.io/abhigyanpatwari/gitnexus-web:latest	akonlabs/gitnexus-web:latest

Heads-up — image rename. Earlier releases published the web UI under ghcr.io/abhigyanpatwari/gitnexus. Starting with the introduction of the bundled backend, that slug now hosts the CLI/server image and the UI moved to ghcr.io/abhigyanpatwari/gitnexus-web. The previous tags remain available for pulling, but new versions are only published under the new slugs. Update your docker run / compose files accordingly (or just adopt the bundled compose).

One-command setup

docker compose up -d

This starts the server on http://localhost:4747 and the web UI on http://localhost:4173. The UI auto-detects the server because the browser runs on the host and reaches the container via the mapped port.

A named volume (gitnexus-data) persists the global registry, indexes, and cloned repos at /data/gitnexus inside the server container. To make repos on your host machine indexable, set WORKSPACE_DIR before bringing the stack up:

WORKSPACE_DIR=$HOME/code docker compose up -d
# Inside the server container the directory is mounted read-only at /workspace.
docker compose exec gitnexus-server gitnexus index /workspace/my-repo

Direct docker run

# Server
docker run --rm -d \
  --name gitnexus-server \
  -p 4747:4747 \
  -v gitnexus-data:/data/gitnexus \
  ghcr.io/abhigyanpatwari/gitnexus:latest

# Web UI
docker run --rm -d \
  --name gitnexus-web \
  -p 4173:4173 \
  ghcr.io/abhigyanpatwari/gitnexus-web:latest

Optional env file (override image tags, container names, ports, workspace dir):

cp .env.example .env
docker compose --env-file .env up -d

Versioning & supply-chain protection

The Docker images are version-locked to the npm package:

• Stable images are only published from vX.Y.Z git tags (via docker.yml triggered directly by the tag push), and the workflow refuses to build unless the tag exactly matches gitnexus/package.json's version. So ghcr.io/abhigyanpatwari/gitnexus:1.6.2 (and its Docker Hub mirror akonlabs/gitnexus:1.6.2) is byte-for-byte the same release as npm install gitnexus@1.6.2 — no drift, no floating builds from main. Both registries receive the same digest from a single build step, so you can pull from either and the signature verifies identically.
• Release-candidate images (e.g. :1.7.0-rc.1) are published alongside each RC npm release. They are built by release-candidate.yml calling docker.yml as a reusable workflow after the RC tag is created and pushed.
• :latest is auto-promoted only from non-prerelease tags by the Docker metadata action, so it always points at a real, npm-published version.

Both images are signed with Cosign keyless signing using the workflow's GitHub OIDC identity, and shipped with build provenance and SBOM attestations. This is your protection against supply-chain attacks: even if an attacker republishes a same-named image elsewhere (or somehow pushes to a typo-squatted registry), they cannot forge a Cosign signature tied to abhigyanpatwari/GitNexus's docker.yml. Always verify before pulling into sensitive environments:

Stable releases — signed from the v* tag ref:

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# Same signature verifies the Docker Hub mirror (identical digest):
cosign verify docker.io/akonlabs/gitnexus:1.6.2 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The regex pins the certificate identity to this repo's docker.yml workflow run from a v* tag — rejecting unsigned images, images signed by other workflows, and images signed from unprotected refs. It is identical for both registries because both sets of tags were signed at the same digest in one workflow run.

Release candidates — signed from refs/heads/main (the caller's ref when release-candidate.yml invokes docker.yml as a reusable workflow):

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
  --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

You can also inspect the build provenance and SBOM:

cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
  --predicate-type https://slsa.dev/provenance/v1

Kubernetes: enforce signatures at admission

For Kubernetes deployments, ship the bundled ClusterImagePolicy so the Sigstore policy-controller rejects any GitNexus pod whose image is not signed by this repo's docker.yml running from a vX.Y.Z tag — the same identity the cosign verify snippet above pins.

# 1. Install the controller (one-time, cluster-wide)
helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
helm install policy-controller -n cosign-system --create-namespace \
  sigstore/policy-controller

# 2. Opt your namespace in
kubectl label namespace <your-ns> policy.sigstore.dev/include=true

# 3. Apply the policy
kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml

After this, attempting to deploy an unsigned image — or one signed by anything other than abhigyanpatwari/GitNexus's docker.yml at a v* tag — fails the admission webhook before a pod is ever created. This turns the verifiable signature into an enforced policy, which is the supply-chain control most clusters actually need.

Files

• Dockerfile.web — builds gitnexus-shared and gitnexus-web, then serves the production frontend.
• Dockerfile.cli — builds the CLI/server (with its native deps) and runs gitnexus serve --host 0.0.0.0.
• docker-compose.yaml — starts both signed images side by side.
• .env.example — overrides for image names, container names, ports, and the workspace mount.

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:

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

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

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

• 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