GitNexus: What You Can Actually Do
With a Code Knowledge Graph

After running gitnexus analyze, you get a KuzuDB graph of your entire codebase. Every function, class, import relationship, and call chain is a node or edge. The CLI commands and MCP tools let you query that graph in ways that grep and file search can’t — you’re searching execution flows, not text matches. You ask “how does X work?” and get the actual call chain from entry point to implementation.

The Tools

Searches for execution flows related to a concept. Returns ranked processes — traced call chains from entry points — not just file matches. Uses BM25 keyword search combined with semantic vector search via Reciprocal Rank Fusion.

gitnexus query "snapshot converter pipeline"
gitnexus query "authentication middleware" --limit 10
gitnexus query "rate limiting" --context "adding throttling to API" --goal "find existing patterns"

When to use: Starting point for understanding how code works together. Complements grep — grep finds text matches, query finds execution flows.

360-degree view of a single function, class, or method. Shows who calls it, what it calls, and which execution flows it participates in.

gitnexus context validateUser
gitnexus context processRecord --file src/converter/handler.ts
gitnexus context --uid "Function:src/auth/validator.ts:validateUser"

When to use: After query finds something interesting, drill into a specific symbol. Before modifying a function, see everything connected to it.

Blast radius analysis. Traverses the graph outward from a symbol and categorizes everything affected by depth.

gitnexus impact processRecord --direction upstream
gitnexus impact AuthService --direction upstream --depth 4
gitnexus impact validateToken --direction downstream --include-tests

Returns a risk level (LOW / MEDIUM / HIGH / CRITICAL) with results organized by distance:

• d=1 (WILL BREAK): Direct callers and importers
• d=2 (LIKELY AFFECTED): Indirect dependents
• d=3 (MAY NEED TESTING): Transitive dependencies

Also lists affected execution flows (which processes break and at which step) and affected modules (which functional areas are hit).

When to use: Before any refactor, rename, or modification to shared code. The risk rating tells you instantly how dangerous the change is.

Maps your uncommitted git changes back to the knowledge graph. Shows which symbols changed and which execution flows are affected.

detect_changes({ scope: "staged" })
detect_changes({ scope: "compare", base_ref: "main" })

Supports four scopes: unstaged (default), staged, all, and compare (diff against a branch). Returns changed symbols, affected processes, and a risk summary.

When to use: Before committing. Before opening a PR. Answers “do I need to test more?”

Finds all references via graph traversal (high confidence) and regex text search (lower confidence). Runs in preview mode by default.

rename({ symbol_name: "processPayment", new_name: "handlePayment" })

Each proposed edit is tagged "graph" (safe to accept) or "text_search" (review carefully). Safer than find-and-replace because it uses the graph to find callers and importers that regex might miss.

This one runs automatically. When Claude Code executes a Grep or Glob, the registered PreToolUse hook runs gitnexus augment <pattern> behind the scenes. It searches the graph for matching symbols and injects callers, callees, and flow participation into the tool result before the agent sees it.

You never call this directly. It makes every search smarter by adding graph context automatically.

Runs an LLM over the knowledge graph and source code to produce a navigable HTML wiki. Groups files into functional modules, generates a page per module with architecture diagrams and cross-module call analysis.

gitnexus wiki                           # Generate wiki for current repo
gitnexus wiki --model gpt-4o            # Use a specific model
gitnexus wiki --gist                    # Publish to GitHub Gist

Incremental — re-running after changes only regenerates affected modules. Output lands at .gitnexus/wiki/index.html.

Raw Graph Queries with Cypher

For anything the high-level tools can’t answer, you can write Cypher queries directly against the knowledge graph. Read-only enforced — CREATE, DELETE, DROP, and other mutations are blocked.

# List functions
MATCH (f:Function) RETURN f.name, f.filePath LIMIT 10

# Find all callers of a function
MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: 'validateUser'})
RETURN a.name, a.filePath

# Find cross-boundary calls into the Auth module
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f)
      -[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community {heuristicLabel: 'Auth'})
WHERE NOT (caller)-[:CodeRelation {type: 'MEMBER_OF'}]->(c)
RETURN caller.name, f.name

Graph Schema

MCP Resources

Available to AI agents as read-only context via READ gitnexus://...:

Typical Workflow

• Index

  gitnexus analyze /path/to/repo — builds the knowledge graph from source
• Explore

  gitnexus query "the thing you care about" — find relevant execution flows
• Drill In

  gitnexus context <symbol_name> — get the full picture of an interesting result
• Before Changing

  gitnexus impact <target> --direction upstream — check blast radius
• After Changing

  detect_changes — verify what you actually affected
• Document

  gitnexus wiki — generate a browsable overview of the codebase

The MCP tools do the same things but are available to AI agents automatically. The augment hook enriches every search the agent performs without explicit tool calls.