GitNexus: Codebase as Knowledge Graph

AI Agents Have a Map Problem

Picture a delivery driver in a city they have never visited. They have a list of street names. They can read individual street signs. But they have no map. They do not know that Elm Street is a dead end, that Main Street becomes a highway after the bridge, or that the fastest route from the warehouse to the hospital goes through the park, not around it.

This is how most AI coding agents interact with your codebase. They can read individual files. They can search for function names. But they do not have a map of how everything connects. When you ask Claude Code to refactor a function, it sees the function. It does not automatically see the fourteen callers scattered across eight files, the three interfaces it implements, or the test suite that will break if the return type changes.

The result is predictable. The agent makes a change that looks correct in isolation but breaks something three call chains away. You catch it in review, explain the dependency, and the agent fixes it. But the next time, it is a different dependency it missed. The problem is not intelligence. The problem is structural awareness.

GitNexus is an open-source tool that addresses this gap directly. It parses your entire codebase into a knowledge graph, then exposes that graph through MCP tools that any compatible AI agent can query. The agent gets a map, not just street signs.

The project hit 14K+ stars on GitHub, gaining over 2,000 stars in a single day. That velocity suggests the problem it solves resonates with a lot of developers.

What GitNexus Actually Builds

When you point GitNexus at a repository, it does not simply index file contents. It constructs a graph database where nodes represent code entities (functions, classes, methods, interfaces, modules) and edges represent relationships (calls, imports, exports, type inheritance, constructor patterns).

Think of it as building a nervous system for your codebase. In a human body, if you touch a hot stove, the signal travels through specific nerve pathways to specific brain regions, which trigger specific muscle responses. Every part of that chain matters. If one nerve is damaged, the whole response fails.

Code works the same way. A user clicks a button. That triggers a handler function. The handler calls a validation service. The validation service queries a database adapter. The adapter uses a connection pool. Change any node in that chain, and everything downstream is affected. GitNexus maps these chains explicitly.

The graph captures several dimensions:

Dependencies. Not just "file A imports file B," but which specific symbols are imported, how they are used, and whether the binding is named or default.

Call chains. Function X calls function Y, which calls function Z. GitNexus traces these paths across file boundaries, giving you the full execution story from entry point to leaf function.

Clusters. Using the Leiden community detection algorithm, GitNexus groups related symbols into functional communities. These are emergent -- the algorithm discovers them from the graph structure, not from folder organization. A cluster might span multiple directories but represent a single cohesive feature.

Execution flows. Starting from entry points (API routes, CLI handlers, event listeners), GitNexus traces complete execution paths through your code. These process traces show how user-facing features actually flow through the system.

How It Works: Six Phases, Zero Servers

The "zero server" part is not marketing. GitNexus genuinely runs entirely on your machine (CLI) or entirely in your browser (Web UI). No code leaves your environment. No backend service processes your source files.

The indexing pipeline has six phases:

Phase 1: Structure. Walk the file tree. Map folder and file relationships. Build the skeleton of the graph.

Phase 2: Parsing. Extract every function, class, method, and interface using Tree-sitter AST extraction. Tree-sitter is the same incremental parsing library used by editors like Neovim and Zed. GitNexus uses language-specific grammars for 13 languages: TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, C, and C++.

Phase 3: Resolution. Resolve imports and function calls across files. This is the hard part. GitNexus applies language-aware resolution logic that handles named imports, default exports, re-exports, type inheritance, and constructor-based type inference. The rules differ significantly between languages -- Python's import system works nothing like Go's package system -- so each language has its own resolver.

Phase 4: Clustering. Apply the Leiden algorithm to detect communities within the graph. The Leiden algorithm (an improvement over Louvain) identifies groups of nodes that are more densely connected to each other than to the rest of the graph. In code terms, it finds modules that form natural functional units.

Phase 5: Processes. Trace execution flows from entry points through call chains. This phase produces the "process" view -- a narrative of how a feature works, from the first function call to the last.

Phase 6: Search. Build hybrid search indexes combining BM25 lexical ranking, semantic embeddings (via HuggingFace transformers.js), and reciprocal rank fusion scoring. This powers the natural-language query interface.

The result is stored in LadybugDB, an embedded columnar graph database. The CLI uses native bindings; the Web UI uses a WebAssembly build. Either way, the graph lives in a .gitnexus/ directory inside your project, and a global registry at ~/.gitnexus/registry.json tracks all indexed repositories.

The Graph RAG Difference

If you have used RAG (Retrieval-Augmented Generation) with code before, you have probably experienced its limitations. Traditional RAG splits your code into chunks, embeds them, and retrieves relevant chunks when the agent asks a question. The problem: code chunks without structural context are like paragraphs ripped from a novel. You get fragments, but you lose the plot.

Graph RAG takes a fundamentally different approach. Instead of retrieving raw text, it retrieves structured relationships. When an agent asks "what happens if I change this function's signature?", GitNexus does not return the function's source code and hope the agent figures out the implications. It returns:

• Every function that calls it (direct dependents)
• Every function that calls those functions (transitive dependents)
• The clusters those functions belong to (affected features)
• The execution flows that pass through it (affected user-facing processes)
• A confidence score for each impact level

This is precomputed intelligence, not on-the-fly analysis. The graph already contains all these relationships. The query is a traversal, not a computation. That means the response is fast and complete rather than slow and approximate.

CLI and MCP Integration

This is where GitNexus becomes directly useful for AI coding workflows. The CLI installs globally via npm:

npm install -g gitnexus

Index your repository:

gitnexus analyze

Or skip the global install entirely:

npx gitnexus analyze

The analyze command walks through all six phases and stores the graph locally. For a medium-sized TypeScript project (say, 500 files), indexing typically takes under a minute.

Connecting to Claude Code

GitNexus exposes an MCP server that any MCP-compatible agent can connect to. For Claude Code:

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

For Cursor, add to ~/.cursor/mcp.json:

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

Once connected, the agent gains access to seven MCP tools:

A single MCP server instance serves all indexed repositories. Connection pooling manages up to five concurrent database connections, with automatic eviction after five minutes of inactivity.

What This Looks Like in Practice

You ask Claude Code to refactor a payment processing function. Without GitNexus, Claude reads the function, makes the change, and you discover later that three webhook handlers and a billing report generator are broken.

With GitNexus, Claude first queries the impact tool. It gets back a depth-grouped dependency list: direct callers at depth 1, their callers at depth 2, and so on. Each entry includes a confidence score. Claude now knows the blast radius before touching a single line. It can plan the refactoring to update all affected call sites, or flag the ones it is unsure about.

The detect_changes tool is equally practical. After making edits, the agent can map its Git diff to affected processes and clusters. If it changed a database adapter and the graph shows that adapter participates in the checkout flow, the authentication flow, and the admin dashboard, the agent knows to verify all three -- not just the one it was originally asked to work on.

GitNexus vs. Termdock's Built-In AST Analysis

If you use Termdock's AST code analysis, you might wonder how GitNexus compares. The honest answer: they solve related but different problems, and they complement each other well.

Termdock's AST analysis is integrated directly into your terminal workflow. It provides real-time structural analysis as you work -- function signatures, type hierarchies, symbol definitions -- without requiring a separate indexing step. It is optimized for speed and immediacy within the terminal multiplexer context. When you are navigating code, reviewing a diff, or writing a skill file, Termdock's AST gives you instant structural context right where you are working.

GitNexus builds a persistent, queryable knowledge graph of your entire codebase. Its strength is cross-repository analysis, community detection, execution flow tracing, and blast radius assessment. The graph persists between sessions and can be queried by any MCP-compatible agent.

Think of it as the difference between a flashlight and a satellite map. The flashlight (Termdock AST) illuminates exactly where you are pointing, instantly, as part of your natural workflow. The satellite map (GitNexus) shows the entire terrain with all roads, rivers, and boundaries marked -- but you need to index it first and query it through tools.

A practical setup uses both:

They do not compete. Use Termdock for the immediate, tactical view. Use GitNexus for the strategic, architectural view.

Setup Walkthrough

Quick Start

# Install globally
npm install -g gitnexus

# Navigate to your project
cd your-project

# Index the codebase
gitnexus analyze

# Configure MCP for your editor
gitnexus setup

The setup command auto-detects installed editors (Claude Code, Cursor, Windsurf) and configures MCP connections for each one.

Generate Skill Files

GitNexus can generate repository-specific skill files that describe your codebase architecture:

gitnexus analyze --skills

This produces skill files that any agent skills-compatible tool can consume, giving agents pre-built architectural knowledge without requiring them to query the graph at runtime.

Web UI

If you prefer a visual interface, GitNexus offers a browser-based explorer at gitnexus.vercel.app. Drag and drop a repository ZIP or paste a GitHub URL. The entire indexing pipeline runs in your browser via WebAssembly. No server upload, no account required.

The Web UI renders the knowledge graph using Sigma.js (WebGL-accelerated), so you can visually explore clusters, trace execution flows, and interact with the Graph RAG agent through a chat interface.

You can also bridge the CLI and Web UI. Running gitnexus serve starts a local HTTP server that the web interface auto-detects, allowing you to browse CLI-indexed repositories without re-uploading them.

Other Useful Commands

# List all indexed repositories
gitnexus list

# Generate LLM-powered documentation
gitnexus wiki

# Clean index data
gitnexus clean

Why This Matters for AI Agent Quality

The fundamental challenge with AI coding agents is not generation quality. Modern models can write syntactically correct, logically sound code. The challenge is context quality. An agent that does not understand the architectural implications of its changes will produce locally correct but globally broken code.

This is not a new problem. Human developers face it too. The difference is that experienced developers build mental models of codebases over months and years. They know that touching the payment module requires updating the audit log because they learned that the hard way six months ago.

AI agents do not have six months. They have one context window. GitNexus compresses months of architectural understanding into a queryable graph that fits into that window on demand.

The broader trend here is significant. Tools like GitNexus represent a shift from "give the agent more text" to "give the agent structured knowledge." RAG was the first step -- retrieve relevant text. Graph RAG is the next step -- retrieve relevant relationships. The agent does not just know what code exists; it knows how code connects.

For teams using AI agents for non-trivial work -- refactoring, feature development, dependency upgrades -- tools that provide structural awareness are not optional. They are the difference between an agent that needs constant supervision and one that can be trusted to understand the consequences of its changes.

GitNexus is open-source (ISC license), actively maintained, and runs without sending your code anywhere. If you are already using MCP-compatible agents, adding it to your workflow takes two commands.

Try it. Index a project you know well. Query the impact of a change you have made before. See whether the graph matches your mental model. If it does, you have just given your AI agent the same understanding that took you months to build.