operations/gitnexus-setup.md

GitNexus Setup Guide

Code intelligence tool — index codebase thành knowledge graph để AI agents hiểu code, phân tích impact, debug, và refactor an toàn.

GitHub: https://github.com/abhigyanpatwari/GitNexus

1. Cài đặt

# Cài global (optional)
npm install -g gitnexus

# Hoặc dùng npx (không cần cài)
npx gitnexus analyze

2. Index từng repo

Chạy trong mỗi git repo riêng biệt:

cd booking-api && npx gitnexus analyze
cd ../booking-web && npx gitnexus analyze
cd ../booking-mobile && npx gitnexus analyze

Mỗi lệnh analyze sẽ:

  • Index cấu trúc repo → tạo .gitnexus/ folder
  • Cài agent skills vào .claude/skills/
  • Đăng ký MCP hooks (Claude Code)
  • Tạo/update AGENTS.md và CLAUDE.md

Options

Flag Mục đích
--force Re-index toàn bộ từ đầu
--embeddings Bật semantic search (chậm hơn, search tốt hơn)
--skip-embeddings Bỏ qua embeddings (nhanh hơn)
--skills Tạo repo-specific skill files
--skip-agents-md Giữ nguyên AGENTS.md custom
--verbose Log chi tiết files bị skip

3. Tạo Repository Group (multi-repo)

Project booking-system có 3 git repos riêng → dùng group để query chéo:

# Tạo group
npx gitnexus group create booking-system

# Add từng repo (dùng registry name, không phải path)
npx gitnexus group add booking-system booking-api booking-api
npx gitnexus group add booking-system booking-web booking-web
npx gitnexus group add booking-system booking-mobile booking-mobile

# Sync contracts giữa các repo
npx gitnexus group sync booking-system

# Verify
npx gitnexus group status booking-system

Group commands

npx gitnexus group list [name]         # Liệt kê groups hoặc xem 1 group
npx gitnexus group sync <name>         # Extract contracts giữa các repos
npx gitnexus group contracts <name>    # Xem contracts đã extract
npx gitnexus group query <name> <q>    # Search execution flows chéo repo
npx gitnexus group status <name>       # Check staleness

4. Cấu hình MCP Server

npx gitnexus setup

Auto-detect editors và cấu hình MCP.

Thủ công — Claude Code

# macOS/Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

Thủ công — Cursor

File ~/.cursor/mcp.json:

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

5. CLI Commands Reference

Core

npx gitnexus analyze [path]    # Index repo
npx gitnexus status            # Trạng thái index hiện tại
npx gitnexus list              # Liệt kê tất cả repos đã index
npx gitnexus clean             # Xóa index repo hiện tại
npx gitnexus clean --all --force  # Xóa tất cả indexes
npx gitnexus mcp               # Start MCP server (stdio)
npx gitnexus serve             # Start HTTP server cho web UI

Wiki (cần LLM API key)

export OPENAI_API_KEY=your_key
npx gitnexus wiki [path]              # Generate wiki
npx gitnexus wiki --model <model>     # Custom model (default: gpt-4o-mini)
npx gitnexus wiki --force             # Regenerate toàn bộ

6. MCP Tools (16 tools)

Sau khi cấu hình MCP, AI agents có access:

Tool Mục đích
gitnexus_query Hybrid search (BM25 + semantic)
gitnexus_context 360° view của 1 symbol (callers, callees, processes)
gitnexus_impact Blast radius analysis trước khi edit
gitnexus_detect_changes Git-diff impact mapping (pre-commit check)
gitnexus_rename Multi-file coordinated rename
gitnexus_cypher Raw graph queries
group_list/sync/contracts/query/status Multi-repo tools

7. Giữ Index Fresh

Sau khi commit code, index sẽ stale. Re-analyze:

npx gitnexus analyze

Nếu trước đó có embeddings:

npx gitnexus analyze --embeddings

Claude Code: PostToolUse hook tự động re-analyze sau git commit và git merge.

8. File Structure

~/.gitnexus/registry.json     ← Global registry (pointers to all indexed repos)

<repo>/.gitnexus/              ← Repo index (PHẢI gitignore)
├── graph.db                   ← Knowledge graph
├── meta.json                  ← Index metadata
└── embeddings/                ← Semantic embeddings (nếu có)

<repo>/.claude/skills/         ← Agent skills (auto-generated)

9. Troubleshooting

Index stale

npx gitnexus status   # Check commit hash
npx gitnexus analyze  # Re-index

MCP không kết nối

# Verify MCP server chạy được
npx gitnexus mcp

# Re-add
claude mcp remove gitnexus
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Embeddings bị mất

Check meta.json → stats.embeddings. Nếu = 0, chạy lại:

npx gitnexus analyze --embeddings

Lưu ý: Chạy analyze KHÔNG có --embeddings sẽ xóa embeddings đã tạo trước đó.