GitNexus: Building Code Intelligence Graphs That Never Leave Your Machine

Hook

Your AI coding assistant doesn't actually understand your codebase architecture—it's just guessing from file snippets within a context window. GitNexus changes that by building a complete knowledge graph of dependencies, call chains, and relationships that runs entirely in your browser.

Context

LLMs have transformed how we write code, but they have a fundamental blindness problem. Tools like GitHub Copilot and ChatGPT see your codebase through a narrow keyhole—they get snippets of files, maybe some git history, but they lack architectural understanding. Ask an LLM to refactor a function and it might miss that three other modules depend on its exact signature. Request a dependency update and it won't know which call chains will break. The problem isn't intelligence—it's context. Traditional solutions require uploading your code to external servers for indexing, creating privacy concerns and vendor lock-in.

GitNexus takes a radically different approach: it's a zero-server code intelligence engine that builds comprehensive knowledge graphs entirely client-side. Drop a GitHub repository or ZIP file into the browser interface, and Tree-sitter parsers (compiled to WebAssembly) extract every import, function call, class inheritance, and dependency relationship into a graph database that never leaves your machine. The CLI version goes further, indexing repositories locally and exposing them through Model Context Protocol (MCP) servers—meaning AI agents in Cursor, Claude Desktop, or other MCP-compatible editors can query your codebase's architecture directly, providing the kind of context that transforms LLMs from clever autocomplete into genuine refactoring partners.

Technical Insight

The architecture hinges on two key decisions: Tree-sitter for parsing and LadybugDB for storage, both available in native and WASM forms. Tree-sitter grammars provide language-agnostic parsing—the same core engine handles TypeScript, Python, Rust, and 15+ other languages by swapping grammar files. In the browser, GitNexus loads Tree-sitter WASM modules and processes files incrementally, building a graph of nodes (functions, classes, variables) and edges (calls, imports, inherits). The CLI uses native Tree-sitter bindings for 5-10x faster parsing on large repositories.

Here's what the MCP integration looks like in practice. After indexing a repository with the CLI, you start the MCP server:

# Index your repository
gitnexus index ./my-project

# Start MCP server (connects to AI agents)
gitnexus mcp-server --graph ./my-project/.gitnexus/graph.db

Now in Cursor or Claude Desktop, you can ask questions like "What functions call the authentication middleware?" or "Show me all modules that depend on the database connection pool." The AI agent queries the MCP server, which traverses the knowledge graph and returns structured results—not fuzzy text search, but precise architectural relationships. The MCP protocol standardizes this interaction, so any MCP-compatible tool can leverage your codebase graph without GitNexus having to build N different editor plugins.

The Graph RAG (Retrieval Augmented Generation) implementation is where things get clever. Traditional RAG chunks code into text embeddings and retrieves similar snippets. Graph RAG uses the knowledge graph structure itself for retrieval. When you ask "How does user authentication work?", GitNexus:

1. Identifies relevant entry points (e.g., /login route handler)
2. Traverses the call graph to find all reachable authentication functions
3. Includes dependency imports and middleware chains
4. Provides this structured context to the LLM

This means smaller models (GPT-4o-mini, Claude Haiku) can compete with larger ones because they're given precise architectural context instead of hoping the right code snippets landed in their context window.

The dual-mode storage strategy solves a critical browser constraint. LadybugDB in WASM mode stores graphs entirely in memory, limiting browser UI to ~5,000 files before tabs crash. But CLI mode writes to native SQLite-backed LadybugDB, persisting graphs to disk. The "bridge mode" lets the web UI connect to a locally-running CLI graph via HTTP, giving you browser-based visualization of large repositories without re-parsing:

// Browser connects to local CLI graph
const graph = await GitNexus.connectBridge('http://localhost:8080');

// Query without re-indexing
const callers = await graph.query({
  type: 'callers',
  target: 'authenticateUser',
  maxDepth: 3
});

This architecture elegantly separates parsing (expensive, done once by CLI) from exploration (interactive, done by web UI). You get the performance of native code with the ergonomics of a browser interface.

The parsing itself extracts more than syntax trees. For TypeScript, GitNexus tracks import/export relationships, function signatures with parameter types, class inheritance chains, and even JSDoc annotations. For Python, it captures module imports, class hierarchies, decorator usage, and function call sites. Each language grammar exposes different AST node types, but GitNexus normalizes them into a common graph schema: Function, Class, Variable, Module nodes connected by Calls, Imports, Inherits, Defines edges. This normalization is what makes cross-language queries possible—you can ask "Which Python modules import TypeScript types" if you're working in a polyglot monorepo.

Gotcha

The biggest limitation is browser memory for the web UI. While the documentation claims ~5,000 files, that's highly dependent on file size and complexity. Parsing a 2,000-file TypeScript monorepo with heavy generics can exceed 2GB of memory, crashing the tab. The CLI handles this fine with native bindings, but if you want the web interface for visualization and sharing, you're stuck using bridge mode—which means you need the CLI installed anyway, undermining the "zero install" promise of the browser version.

Language support requires compilation for optional grammars. Out of the box, GitNexus supports JavaScript, TypeScript, Python, Rust, Go, Java, C, C++, and a few others using precompiled WASM grammars. But Dart and Protocol Buffers require building Tree-sitter grammars from source, which means installing python3, make, and g++ on your machine. The GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 flag bypasses this, but then you simply can't parse those languages. For teams with Flutter codebases or heavy protobuf usage, this creates an awkward choice between build toolchain setup or losing language support.

The PolyForm Noncommercial License is deceptively restrictive for an "open-source" project with 36,000+ stars. You can use GitNexus for personal projects and open-source work, but any commercial use—including internal tools at for-profit companies—technically requires an enterprise license. The repository doesn't clarify pricing or how to obtain commercial licenses, creating legal ambiguity for engineering teams who want to adopt it.

Verdict

Use if: You're working with AI coding assistants and frustrated by their lack of architectural awareness—GitNexus's MCP integration gives Cursor and Claude Desktop the context they need to suggest accurate refactorings. Use if privacy is non-negotiable and you can't upload code to external indexing services. Use if you're exploring unfamiliar open-source codebases and want a visual knowledge graph to understand module relationships quickly. The CLI mode is particularly valuable for daily development workflows where you want persistent, fast indexing. Skip if: You need commercial use without legal complexity—the licensing situation is unclear. Skip if your primary languages are Dart or Proto and you can't set up C++ build tools. Skip if you prefer battle-tested code search tools like Sourcegraph and need enterprise features like team collaboration, code monitoring, or batch changes. Skip if your repositories are enormous (50,000+ files) and you want browser-based exploration without running separate CLI infrastructure.