GitNexus — Codebase Knowledge Graph

Binary: gitnexus (installed at ~/.npm-global/bin/gitnexus) Install: npm install -g gitnexus (v1.3.6+) Languages: JS/TS/Python/Rust/Go/Java (Tree-sitter based)

When to Use

• Debugging complex bugs across multiple files
• Understanding unfamiliar codebases quickly
• Finding all callers/dependencies of a function
• Tracing execution flows end-to-end
• Code review with full architectural context
• Catching dead code, missing imports, circular deps

Quick Reference

Index a repo

gitnexus analyze [path]              # Index or update (incremental)
gitnexus analyze --force             # Full re-index (after major refactors)
gitnexus analyze --skip-embeddings   # Faster, no semantic search
gitnexus analyze --embeddings        # Enable embeddings for semantic queries

Query via MCP (preferred for agent use)

gitnexus mcp                         # Start MCP server (stdio)

MCP tools available:

• get_nodes — List all indexed nodes (functions, classes, files)
• get_edges — List all relationships (calls, imports, exports)
• get_clusters — Show module clusters
• get_flows — Trace execution flows
• search_code — Full-text search across indexed code
• get_dependencies — Find all deps of a node
• get_dependents — Find all callers of a node

CLI management

gitnexus list                        # All indexed repos
gitnexus status                      # Index status for current repo
gitnexus clean                       # Delete index
gitnexus serve                       # HTTP server for web UI bridge

Web UI

• Online: https://gitnexus.vercel.app
• Local bridge: gitnexus serve then open web UI

Workflow for Bug Hunting

1. Index the repo:

   cd /path/to/repo && gitnexus analyze
   

2. Start MCP and query — or read generated files:

   • AGENTS.md / CLAUDE.md — auto-generated codebase context
   • .claude/skills/gitnexus/ — agent skill files with knowledge

3. For quick checks without MCP, read generated context files directly.

Editor Integration

gitnexus setup                       # Auto-configure MCP for detected editors
# Or manual:
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Tips

• Re-run gitnexus analyze after significant code changes (incremental)
• Use --force after major refactors
• Index stored in .gitnexus/ in repo root
• For large repos (>5k files), CLI mode is better than web UI

Pitfalls

• Don't run on repos with massive node_modules — exclude or use .gitignore
• MCP server is stdio-based, meant for agent integration not HTTP
• gitnexus wiki requires OPENAI_API_KEY or GITNEXUS_API_KEY — fails hard otherwise. For agent use without an LLM key, query KuzuDB directly (see below).
• --skip-embeddings is not a valid flag (that's the default). Use --embeddings to opt IN, omit to opt out. Running analyze without --embeddings deletes any existing embeddings.

Direct KuzuDB Query (No MCP, No LLM Key)

When the MCP server isn't wired and wiki is unavailable, query the graph directly via Node:

// /tmp/gn_dump.js — run with `cd <repo> && node /tmp/gn_dump.js`
const { Database, Connection } = require("${HOME}/.npm-global/lib/node_modules/gitnexus/node_modules/kuzu");
const db = new Database(".gitnexus/kuzu", 0, true, true);  // read-only
const conn = new Connection(db);

async function run(q, label, max=50) {
  console.log("\n=== " + label + " ===");
  const r = await conn.query(q);
  const rows = await r.getAll();
  rows.slice(0, max).forEach(row => console.log(JSON.stringify(row)));
  if (rows.length > max) console.log(`... +${rows.length - max} more`);
}

(async () => {
  // Discover schema
  await run("CALL show_tables() RETURN *", "tables");
  // Sample a node to see properties
  await run("MATCH (p:Process) RETURN p.* LIMIT 1", "process schema");
  // Top execution flows
  await run("MATCH (p:Process) RETURN p.label, p.stepCount, p.entryPointId, p.terminalId ORDER BY p.stepCount DESC", "PROCESSES");
  // Clusters by size
  await run("MATCH (c:Community) RETURN c.label, c.symbolCount, c.cohesion ORDER BY c.symbolCount DESC", "CLUSTERS");
  // "God nodes" — most-connected functions/classes (architectural load-bearers)
  await run(`MATCH (n)-[r:CodeRelation]-() WHERE label(n) IN ['Function','Class','Method','Interface']
             RETURN n.id as id, count(r) as deg ORDER BY deg DESC LIMIT 25`, "TOP DEGREE NODES");
})();

Cypher gotchas (Kuzu dialect)

• desc is a reserved word — never use it as a column alias. Use direction or skip the alias.
• Property access: c.label is fine, but to discover properties first use RETURN c.* LIMIT 1 (returns each prop as c.propName).
• Relationship table is CodeRelation (single table, types stored as property), not :CALLS / :IMPORTS.
• Read-only mode: pass 4th arg true to Database() constructor.

Useful node tables

When to use this fallback

• Cron jobs / sub-agents without MCP
• Quick architecture audit when LLM budget matters (free, ~3s per query)
• "Big picture" reports: clusters + processes + top-degree nodes give a complete topology in one Node script
• Combine with find ... -name '*.ts' \| xargs wc -l for LoC-per-cluster sizing

Verification

gitnexus --version                          # Confirm v1.3.6+ installed
cd /tmp && git init test-repo && cd test-repo && echo "fn main(){}" > main.rs
gitnexus analyze .                          # Should index 1 file, exit 0
gitnexus status                             # Should show indexed file count