GitNexus: Building Knowledge Graphs for AI Code Agents Without Servers
Hook
What if your AI coding assistant could trace the exact call chain from a button click to a database query across twelve files—without you explaining anything? GitNexus makes that possible by giving AI agents a queryable map of your entire codebase’s relationships.
Context
Modern AI coding assistants like Claude and Cursor struggle with architectural awareness. They excel at writing individual functions but fail spectacularly when changes ripple across multiple files. Ask Claude to refactor an authentication flow, and it might miss that your logout function is called from seven different components, each with different error-handling requirements. The assistant has context length but lacks context structure.
Traditional code intelligence tools—LSPs, ctags, even Sourcegraph—were built for human developers navigating code manually. They answer “where is this function defined?” beautifully but can’t tell an AI agent “what will break if I change this signature?” GitNexus attacks this gap by building process-aware knowledge graphs that track not just definitions and imports, but execution flows, call chains, and cross-file dependencies. Then it exposes these graphs through the Model Context Protocol (MCP), turning them into queryable knowledge bases that AI agents can reason about. The entire system runs client-side—in your terminal via CLI or in your browser via WASM—with zero server infrastructure.
Technical Insight
GitNexus’s architecture revolves around three core components: a Tree-sitter parsing layer, LadybugDB (a custom graph database), and an MCP server that speaks to AI agents. The parsing layer handles polyglot codebases by using Tree-sitter grammars to extract AST nodes, then walking those trees to identify relationships. Unlike traditional AST analyzers that stop at syntax, GitNexus builds semantic edges—function calls, type dependencies, import chains, and execution flows.
The graph database stores these relationships as nodes (functions, classes, files) and edges (calls, imports, extends). When you index a repository, GitNexus creates entries like “function authenticateUser in auth.ts CALLS validateToken in token.ts” and “HomePage component IMPORTS useAuth from hooks/auth.ts.” The magic happens when you chain these: asking “what depends on this database schema?” traces edges backward through ORM models, service layers, API handlers, and UI components.
Here’s where MCP integration transforms the experience. GitNexus exposes seven specialized tools that AI agents can invoke:
// MCP tools available to AI agents
const tools = [
'search_files', // Find files by name/path pattern
'search_symbols', // Locate functions, classes, types
'get_call_graph', // Trace who calls this function
'get_dependency_graph', // Map import/require relationships
'get_execution_flow', // Follow runtime call sequences
'analyze_impact', // Predict change propagation
'find_related_code' // Semantic similarity search
];When you ask Claude Code to refactor that authentication flow, it can first invoke get_call_graph('authenticateUser') to discover all callers, then get_execution_flow('login') to trace the complete authentication sequence, and finally analyze_impact('auth.ts') to predict what breaks. The agent doesn’t guess—it queries.
The dual-deployment architecture is particularly clever. The CLI uses native Tree-sitter bindings and runs Node.js for maximum performance—it can index a 10k-file repo in under a minute. The browser version compiles the same core engine to WASM, letting you drag-drop a ZIP file and get an interactive graph without installing anything. Both modes produce identical graph databases, which enables “bridge mode”: index locally with the CLI for speed, then browse the graph in the web UI for visualization. The graph file is just a portable SQLite database that works everywhere.
The Claude Code integration adds PreToolUse and PostToolUse hooks that make the assistant context-aware automatically. Before invoking any tool, the PreToolUse hook searches the knowledge graph for relevant symbols and injects them into the prompt. After a commit, the PostToolUse hook triggers re-indexing of changed files and updates the graph incrementally. This means the AI’s understanding of your codebase evolves as you code:
// Simplified hook behavior
async function onToolUse(tool, args, context) {
if (context.phase === 'pre') {
// Enrich prompt with graph context
const symbols = await graph.search_symbols(args.query);
const callers = await graph.get_call_graph(symbols[0]);
return { additionalContext: { symbols, callers } };
}
if (context.phase === 'post' && tool === 'write_file') {
// Update graph after file changes
await graph.reindex(args.path);
}
}This architecture delivers something profound: AI assistants that understand not just syntax but architecture. When GPT-4 or Claude queries “what happens if I change this API response format?”, GitNexus traces the propagation path through parsers, state managers, UI components, and test fixtures. Smaller models become competitive with larger ones because the graph compensates for limited reasoning with precise structural knowledge.
Gotcha
The browser mode’s ~5k file limit is a hard constraint, not a soft guideline. WASM memory limits and browser tab restrictions mean large monorepos will crash the UI. Bridge mode mitigates this—index locally, browse remotely—but that requires running the CLI, which defeats the zero-install promise for bigger projects. If your primary codebase is a 50k-file monorepo, the web experience won’t work without architectural compromises.
The PolyForm Noncommercial license is a deal-breaker for many teams. You can use GitNexus freely for personal projects, open-source work, and academic research, but commercial use requires a separate license. This isn’t unusual for dual-licensed developer tools, but it means you can’t just deploy this at your startup or Fortune 500 without legal review. The technical capabilities might justify the cost, but the friction is real. Also, language coverage depends entirely on Tree-sitter parser availability—running with the --verbose flag reveals skipped files when parsers are missing, which can be surprising for niche languages or DSLs.
Verdict
Use if: You’re leveraging AI coding assistants like Claude Code or Cursor and need them to understand architectural dependencies, not just syntax. GitNexus shines for coordinated refactoring across multiple files, impact analysis before changing shared utilities, and giving AI agents reliable context about execution flows. It’s perfect for medium-sized TypeScript/JavaScript/Python projects where visual code exploration and AI-assisted development are core workflows. The MCP integration is genuinely transformative if you’re already in that ecosystem. Skip if: You need a commercial license without budget approval, work exclusively on massive monorepos in the browser without CLI access, or aren’t using AI coding assistants at all—traditional LSP tools will be simpler. Also skip if you need enterprise features like team collaboration, access controls, or SLA guarantees. GitNexus is a powerful solo-developer or small-team tool, not an enterprise platform.
