GitNexus: Knowledge Graph Giúp AI Agents Thực Sự Hiểu Codebase Của Bạn
GitNexus index codebase thành knowledge graph — dependency, call chain, cluster, execution flow — rồi cung cấp qua MCP tools để AI agent không bỏ sót code nào.

GitNexus index codebase thành knowledge graph có thể truy vấn và expose cho AI agent qua MCP — để refactor không còn làm vỡ code mà model chưa từng mở.
⚡ TL;DR
GitNexus là công cụ MCP giúp AI agent hiểu cấu trúc codebase, không chỉ từng file riêng lẻ. Nó cũng có giao diện trực quan hoá dạng đồ thị khi bạn muốn khám phá mà không cần gắn vào editor.
- Nó giải quyết gì: Xây dựng knowledge graph của codebase và expose qua MCP tools để AI agents hiểu impact của mỗi thay đổi
- Tại sao quan trọng: Nếu không có nó, AI refactor code bề ngoài tốt nhưng vô tình break 47 functions phụ thuộc mà nó không thấy
- Dùng cho ai: Developers dùng Cursor, Claude Code, Windsurf hay bất kỳ AI coding assistant nào
- Khác biệt chính: Tính toán trước graph intelligence (clustering, execution flow, blast radius) thay vì hy vọng LLM dò đủ
Bản Đồ Cho Người Mới
Đừng đọc GitNexus như bảy MCP tools rời rạc. Hãy đọc theo một đường: index một lần vào KuzuDB, truy vấn nhiều lần qua MCP.
- Lượt 1: Phần 1 — pattern refactor mù (
UserService.validate()). - Lượt 2: Phần 2 — xem scene năm beat; nhớ
analyze → KuzuDB → MCP. - Lượt 3: Phần 3 — tools theo thứ tự quan trọng (
impacttrước, rồicontext,query, …). - Lượt 4: Phần 4 — chạy bài tập thực hành bên dưới trên repo bạn đang sửa.
| Thuật ngữ | Trả lời câu hỏi |
|---|---|
| KuzuDB | Graph đã index nằm ở đâu? |
analyze |
Làm sao dựng graph từ repo? |
| MCP | Agent trong editor chạm graph bằng cách nào? |
impact |
Đổi symbol này thì cái gì sẽ vỡ? |
| Processes | Execution flow nào (vd. LoginFlow) chạm code này? |
gitnexus serve |
CLI index và Web UI dùng chung graph thế nào? |
Bài Tập Thực Hành Đầu Tiên
Sau npx gitnexus analyze và npx gitnexus setup ở Phần 4, mở Cursor hoặc Claude Code và hỏi:
“Trước khi refactor UserService, dùng GitNexus impact để liệt kê upstream dependents kèm confidence score.”
Nếu agent trả về bản đồ blast radius có cấu trúc thay vì grep tên file, beat 3 trong scene Phần 2 vừa trở thành thực tế — phần còn lại của bài chỉ là chi tiết cho các mũi tên bạn đã xem animate.
Mở rộng: sau khi sửa file, nhờ agent chạy detect_changes trước khi commit. Vòng lặp đó nối impact ở beat 3 với lưới an toàn pre-commit ở Phần 3.
Phần 1: Nền Tảng — Mô Hình Tư Duy
Tưởng tượng bạn là bác sĩ phẫu thuật chuẩn bị mổ. Bạn có X-quang thấy xương, nhưng không thấy dây thần kinh, mạch máu, hay cách chúng kết nối. Bạn cắt một nhát — và trúng động mạch mà không ai đề cập.
Đó chính xác là điều xảy ra khi AI agents chỉnh sửa code ngày nay.
Các tool như Cursor, Claude Code, Windsurf, và Cline là những trình soạn thảo code cực kỳ mạnh. Nhưng chúng có chung một điểm mù cốt lõi: chúng không thực sự hiểu cấu trúc codebase của bạn. Chúng thấy files, thấy functions, nhưng không thấy mạng lưới dependencies vô hình kết nối mọi thứ.
Đây là pattern thất bại điển hình:
- Bạn yêu cầu AI refactor
UserService.validate() - AI chỉnh sửa hoàn hảo — trong phạm vi riêng lẻ
- AI không biết 47 functions phụ thuộc vào return type của nó
- Breaking changes được push lên production
GitNexus giải quyết vấn đề này bằng cách xây dựng một knowledge graph hoàn chỉnh của codebase — mọi function call, import, class inheritance, và execution flow — rồi expose qua smart tools thông qua Model Context Protocol (MCP).
Hình dung thế này:
Không có GitNexus: AI agent của bạn di chuyển trong codebase như khách du lịch với bản đồ tên đường.
Có GitNexus: AI agent di chuyển như dân địa phương biết mọi đường tắt, ngõ cụt, và đường một chiều.
Ẩn dụ đó mô tả đúng khoảng trống — nhưng vẫn còn trừu tượng. Phần 2 biến nó thành một đường đi cụ thể: từ refactor mù ở beat 1, qua npx gitnexus analyze dựng graph trong KuzuDB, đến lúc agent gọi impact() trước khi chạm vào UserService.
Phần 2: Khám Phá — GitNexus Xây Dựng “Bộ Não” Như Thế Nào
Phần 1 đặt tên cho điểm mù. Phần 2 cho thấy GitNexus lấp nó bằng cách nào.
Ở mức cao, GitNexus làm ba việc theo thứ tự:
- Index — duyệt repo qua pipeline sáu giai đoạn và lưu knowledge graph vào KuzuDB
- Expose — phục vụ graph đó cho editor qua MCP tools (
impact,context,query, …) - Deliver — chạy cùng một “bộ não” trên CLI (local), Web UI (browser), hoặc nối hai phía bằng
gitnexus serve
Danh sách bullet trong README che mất trình tự đó. Trước khi mở từng giai đoạn pipeline, từng MCP tool và lệnh setup, hãy xem một câu chuyện chạy qua năm beat — xương sống giống nhau dù bạn index từ terminal hay khám phá trên browser.
Coi animation như các chương của cùng một câu chuyện:
- Without graph context — pattern thất bại ở Phần 1, giờ thành luồng (editor → agent → sửa lẻ)
- Six-stage indexing —
analyzeđi Structure → Search rồi ghi vào KuzuDB - Precomputed graph queries — MCP trả blast radius và process context trong một lần gọi
- CLI, Web, bridge mode — ba cách chạm cùng một graph
- Full picture — zoom out; mọi mục bạn đọc phía dưới gắn vào stack này
Câu xương sống cần nhớ: analyze → KuzuDB → MCP → agent tools. Beat 2 dựng graph một lần; beat 3 là lúc refactor mù dừng lại — agent truy vấn cấu trúc đã tính sẵn thay vì đoán từ tên file.
Dùng bảng này khi một beat kết thúc và bạn muốn đọc sâu hơn:
| Beat trong scene | Đọc tiếp ở đâu |
|---|---|
| Without graph context | Phần 1 — pattern thất bại với UserService.validate() |
| Six-stage indexing | § Pipeline bên dưới + Precomputed Intelligence |
| Precomputed graph queries | Phần 3 — đủ 7 MCP tools |
| CLI, Web, bridge mode | Phần 4 — Bắt đầu |
| Full picture | Bảng Mô Hình Tư Duy Cuối Cùng ở cuối bài |
Pipeline Index Đa Giai Đoạn
Beat 2 trong scene trên chính là pipeline này đang chạy. Khi bạn gõ npx gitnexus analyze, GitNexus xử lý codebase qua sáu giai đoạn — sơ đồ ASCII bên dưới là cùng một đường đi, với tên giai đoạn ghi rõ để tra cứu:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 1. Structure │───▶│ 2. Parsing │───▶│ 3. Resolution│
│ File tree + │ │ Tree-sitter │ │ Cross-file │
│ folder map │ │ AST extract │ │ imports │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 6. Search │◀───│ 5. Processes │◀───│ 4. Clustering │
│ Hybrid index │ │ Execution │ │ Community │
│ BM25+Vector │ │ flow tracing │ │ detection │
└──────────────┘ └──────────────┘ └──────────────┘
Giai đoạn 1 — Structure: Map file tree và quan hệ thư mục. Đây là bộ khung xương.
Giai đoạn 2 — Parsing: Sử dụng Tree-sitter để trích xuất mọi function, class, method, và interface từ 11 ngôn ngữ: TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, và Swift.
Giai đoạn 3 — Resolution: “Phép thuật” xảy ra ở đây. GitNexus resolve imports và function calls xuyên files với logic nhận diện ngôn ngữ. Nó không chỉ biết auth.ts tồn tại — nó biết handleLogin() trong auth.ts gọi validate() trong user.ts với độ tin cậy 90%.
Giai đoạn 4 — Clustering: Nhóm các symbols liên quan thành communities chức năng sử dụng graph algorithms qua Graphology. Các auth functions, database layer, và API routes tự nhiên cluster với nhau.
Giai đoạn 5 — Processes: Trace execution flows từ entry points xuyên suốt call chains. Nó map ra “LoginFlow” là process 7 bước từ route handler → validation → database → response.
Giai đoạn 6 — Search: Xây dựng hybrid search index kết hợp BM25 (keyword), semantic embeddings (qua HuggingFace transformers.js), và Reciprocal Rank Fusion để truy xuất nhanh.
Mỗi node animate ở beat 2 khớp trực tiếp với một giai đoạn:
| Node trong scene (beat 2) | Giai đoạn | Việc cần làm (một dòng) |
|---|---|---|
| Structure | 1 | File tree và quan hệ thư mục |
| Parsing | 2 | Trích xuất AST bằng Tree-sitter |
| Resolution | 3 | Import và call link xuyên file |
| Clustering | 4 | Communities chức năng qua Graphology |
| Processes | 5 | Execution flows (vd. LoginFlow) |
| Search | 6 | Hybrid index BM25 + embeddings + RRF |
| KuzuDB | — | Graph đã lưu — mọi tool đọc từ đây |
Đổi Mới Cốt Lõi: Precomputed Intelligence
Đó là lý do beat 3 trong scene trả lời gần như tức thì: phần nặng đã xong lúc index.
Các cách tiếp cận Graph RAG truyền thống đổ raw graph edges cho LLM rồi hy vọng nó dò đủ. GitNexus tính toán trước ngay khi index — clustering, tracing, confidence scoring — để mỗi tool call trả về context hoàn chỉnh trong một query duy nhất.
| Graph RAG điển hình | GitNexus | |
|---|---|---|
| Khi nào làm việc nặng | Chủ yếu lúc query (LLM tự dò) | Chủ yếu lúc index (pipeline + KuzuDB) |
| Agent nhận gì | Raw edges; độ đầy đủ phụ thuộc exploration | Gói context đã tính sẵn qua MCP tools |
| Blast radius | Có thể cần nhiều query follow-up | impact trả depth + confidence một lần |
| Phù hợp nhất | Chat nghiên cứu mở | Refactor, rename, kiểm tra trước commit |
Điều này có nghĩa:
- LLM không thể bỏ sót context — nó đã sẵn trong tool response
- Tiết kiệm tokens — không cần chuỗi 10 queries để hiểu một function
- Dân chủ hóa models — LLM nhỏ hơn cũng hoạt động tốt vì tools lo phần nặng
Tech Stack
GitNexus chạy ở hai chế độ, mỗi cái với tech phù hợp:
| Layer | CLI (Local) | Web (Browser) |
|---|---|---|
| Parsing | Tree-sitter native | Tree-sitter WASM |
| Database | KuzuDB native | KuzuDB WASM |
| Embeddings | transformers.js (GPU/CPU) | transformers.js (WebGPU/WASM) |
| Agent Interface | MCP (stdio) | LangChain ReAct agent |
| Visualization | — | Sigma.js + Graphology (WebGL) |
Mọi thứ lưu trong KuzuDB, embedded graph database có hỗ trợ vector — không cần database server bên ngoài. Một kho lưu trữ duy nhất đó là nguồn mà CLI, Web UI và MCP cùng đọc trong beat 3–4 của scene.
Bảng trên là beat 4 ở dạng tĩnh: stack native trên nhánh CLI, stack WASM trên browser, cùng một hình dạng graph.
Phần 3: Chẩn Đoán — GitNexus Thực Sự Làm Gì Cho Developers
Phần 2 kết thúc với graph trong KuzuDB. Phần 3 là beat 3 đi vào thực chiến: agent làm gì với graph đó sau khi MCP đã kết nối.
Scene đã demo ba lệnh — impact, context, và query. GitNexus cung cấp bảy MCP tools. Dùng bảng tóm tắt trước, rồi cuộn xem output mẫu từng tool.
| Tool | Hỏi khi… | Có trong scene? |
|---|---|---|
impact |
Cần blast radius trước khi sửa symbol | beat 3 |
context |
Cần callers, callees và process membership | beat 3 |
query |
Cần tìm theo process, không phải grep thô | beat 3 |
detect_changes |
Cần đánh giá rủi ro diff trước commit | — |
rename |
Cần rename multi-file nhận biết graph | — |
cypher |
Cần truy vấn graph thô (power users) | — |
list_repos |
Quản lý nhiều repo đã index | — |
Quy trình agent khuyến nghị (khớp thứ tự gọi ở beat 3):
impact— trước khi sửa: upstream nào sẽ vỡ?context— trên symbol sắp chạm: callers, callees, processes- Edit — để agent refactor với context từ graph
detect_changes— trước commit: mức rủi ro và processes bị ảnh hưởngrename— khi đổi tên symbol phối hợp nhiều file, không phải sửa một dòng
Các tool không có trong scene (detect_changes, rename, cypher, list_repos) vẫn đọc cùng graph KuzuDB mà beat 2 dựng — chúng là bề mặt tùy chọn trên cùng xương sống.
7 Tools Cho AI Agents “Tia X” Xuyên Code
1. impact — Phân Tích Blast Radius
Trước khi chạm vào code, hỏi: “Cái gì sẽ vỡ?”
impact({target: "UserService", direction: "upstream", minConfidence: 0.8})
TARGET: Class UserService (src/services/user.ts)
UPSTREAM (phụ thuộc vào nó):
Depth 1 (SẼ VỠ):
handleLogin [CALLS 90%] -> src/api/auth.ts:45
handleRegister [CALLS 90%] -> src/api/auth.ts:78
UserController [CALLS 85%] -> src/controllers/user.ts:12
Depth 2 (CÓ THỂ ẢNH HƯỞNG):
authRouter [IMPORTS] -> src/routes/auth.ts
Giống như có một senior engineer đã thuộc lòng toàn bộ codebase nói: “Nếu bạn thay đổi UserService, 4 thứ này SẼ vỡ, và 2 thứ này CÓ THỂ vỡ.”
2. context — Góc Nhìn 360° Về Symbol
Lấy bức tranh toàn diện của bất kỳ symbol nào — ai gọi nó, nó gọi gì, và tham gia processes nào:
context({name: "validateUser"})
incoming:
calls: [handleLogin, handleRegister, UserController]
imports: [authRouter]
outgoing:
calls: [checkPassword, createSession]
processes:
- name: LoginFlow (step 2/7)
- name: RegistrationFlow (step 3/5)
3. query — Tìm Kiếm Theo Process
Không chỉ “tìm files chứa X”, mà “tìm các processes và execution flows liên quan đến X”:
query({query: "authentication middleware"})
processes:
- summary: "LoginFlow"
priority: 0.042
symbol_count: 4
process_type: cross_community
step_count: 7
process_symbols:
- name: validateUser
type: Function
filePath: src/auth/validate.ts
process_id: proc_login
step_index: 2
4. detect_changes — Lưới An Toàn Trước Commit
Trước khi commit, hiểu tác động thực sự của thay đổi:
detect_changes({scope: "all"})
summary:
changed_count: 12
affected_count: 3
risk_level: medium
affected_processes: [LoginFlow, RegistrationFlow]
5. rename — Rename Phối Hợp Multi-File
Không phải find-and-replace đơn giản, mà rename nhận biết graph — phân biệt giữa function tên validate và comment chứa từ “validate”:
rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})
files_affected: 5
total_edits: 8
graph_edits: 6 (độ tin cậy cao)
text_search_edits: 2 (cần review cẩn thận)
6 & 7. cypher và list_repos
Raw Cypher graph queries cho power users, và khám phá repository cho multi-repo setups.
Use Case Thực Tế: Python Developers
Tưởng tượng bạn đang làm việc trên dự án Django với 200+ models. Bạn cần rename một model field. Không có GitNexus, bạn sẽ:
greptên field (bắt luôn comments, strings, matches không liên quan)- Trace thủ công serializers, views, và templates
- Hy vọng không bỏ sót queryset filter nào đó
Với GitNexus: impact({target: "User.email", direction: "upstream"}) → bản đồ dependency hoàn chỉnh tức thì. Đó chính là mũi tên impact bạn thấy ở beat 3 — giờ gắn với ví dụ Django quy mô lớn.
Phần 4: Giải Pháp — Bắt Đầu Như Thế Nào
Bạn đã có mô hình tư duy (Phần 1), pipeline (Phần 2) và tools (Phần 3). Phần 4 là beat 4: dựng index trên CLI, cắm MCP vào editor, xem nhanh trên browser, hoặc nối hai phía bằng gitnexus serve.
| Nhánh beat 4 | Lệnh / URL | Bạn nhận được |
|---|---|---|
| CLI index | npx gitnexus analyze |
KuzuDB native trên disk + skills/hooks |
| MCP wiring | npx gitnexus setup |
Editor nói chuyện với graph (beat 3) |
| Web explore | gitnexus.vercel.app | KuzuDB WASM trong browser |
| Bridge | gitnexus serve |
Web UI đọc index CLI, không upload lại |
CLI Quick Start (Khuyến Nghị)
Đây là nhánh trái của beat 4 — Dev → Analyze → KuzuDB trên đường native:
# Index repository (chạy từ root repo)
npx gitnexus analyze
# Vậy thôi! Lệnh này làm tất cả:
# - Index codebase
# - Cài đặt agent skills
# - Đăng ký Claude Code hooks
# - Tạo files AGENTS.md / CLAUDE.md
Kết Nối Với Editor
Khi graph đã có, đây là cách vẽ mũi tên Editor → MCP trên máy bạn:
# Tự động cấu hình MCP cho tất cả editors phát hiện được
npx gitnexus setup
# Hoặc thủ công cho Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
Ma Trận Hỗ Trợ Editor
| Editor | MCP | Skills | Hooks | Mức Hỗ Trợ |
|---|---|---|---|---|
| Claude Code | ✅ | ✅ | ✅ PreToolUse | Đầy đủ |
| Cursor | ✅ | ✅ | — | MCP + Skills |
| Windsurf | ✅ | — | — | MCP |
| OpenCode | ✅ | ✅ | — | MCP + Skills |
Web UI (Khám Phá Nhanh)
Đây là nhánh phải của beat 4 — Dev → WebUI → KuzuDB mà không cần cài local:
Không cần cài đặt — chỉ cần truy cập gitnexus.vercel.app. Upload repo hoặc paste GitHub URL. Mọi thứ chạy trong browser — không có code nào gửi tới server.
Bridge Mode
Đây là mũi tên Analyze ~> WebUI trong beat 4 — index CLI một lần, duyệt mọi nơi:
Chạy gitnexus serve để kết nối CLI và Web:
# Start local server
gitnexus serve
# Web UI tự phát hiện — duyệt tất cả repos đã index bằng CLI
# không cần upload hay index lại
Wiki Generation
Sau beat 4, bạn có thể biến graph đã index thành tài liệu đọc được — hữu ích cho onboarding hoặc mô tả PR:
gitnexus wiki
gitnexus wiki --model gpt-4o
gitnexus wiki --force # Tạo lại hoàn toàn
Coi wiki như export mô hình tư duy của beat 5 thành prose mà team có thể đọc mà không cần mở editor.
Khi Nào Cần Re-Index
Graph là snapshot. Chạy lại npx gitnexus analyze khi:
- Bạn merge refactor lớn hoặc đổi public API xuyên nhiều file
- Thêm ngôn ngữ hoặc module tree mà index chưa từng thấy
- MCP tools trả path cũ sau khi shuffle thư mục lớn
Sửa code hàng ngày không cần re-index đầy đủ — detect_changes hoạt động trên diff hiện tại.
Mô Hình Tư Duy Cuối Cùng
Beat 5 ở scene Phần 2 chính là bảng này dưới dạng hình — toàn bộ stack gom lại một chỗ. Giữ nó như “checksum” sau khi đã đi qua chi tiết:
| Khía Cạnh | Mô Tả |
|---|---|
| Là gì | Engine knowledge graph index codebases thành graph database có thể query |
| Tech cốt lõi | Tree-sitter (AST) + KuzuDB (graph DB) + HuggingFace (embeddings) |
| Giao diện | 7 MCP tools cho AI agents, CLI cho developers, Web UI để khám phá |
| Insight chính | Precomputed relational intelligence > raw graph traversal |
| Ngôn ngữ | TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Swift |
| Privacy | Mọi thứ chạy local (CLI) hoặc trong browser (Web). Zero data rời máy bạn |
| So với DeepWiki | DeepWiki giúp bạn hiểu code. GitNexus giúp bạn phân tích code |
Kết Luận
- Vấn đề: AI agent sửa symbol trong phạm vi lẻ và bỏ sót code phụ thuộc chưa từng mở.
- Cơ chế: Index một lần (
analyze→ KuzuDB), truy vấn nhiều lần (MCP tools với graph intelligence tính sẵn). - Lợi ích: Ít refactor gây vỡ hơn, rename nhận biết graph, kiểm tra rủi ro trước commit — không gửi codebase lên cloud indexer.
GitNexus không thay thế AI coding assistant. Nó cho assistant trí nhớ kiến trúc để ánh đỏ beat 1 không bao giờ lên production.
Bài viết liên quan
Giải Mã AI Berkshire: Biến Claude Code và Codex Thành Một Team Đầu Tư Có Kỷ Luật
Phân tích thực chiến về AI Berkshire: framework nghiên cứu đầu tư giá trị theo mô hình multi-agent, có cơ chế chống thiên kiến và kiểm định số liệu.
OmniRoute Giải Thích: AI Gateway Miễn Phí Không Để Công Cụ Của Bạn Bị Khựng Lại
OmniRoute là AI gateway mã nguồn mở hợp nhất 290+ nhà cung cấp, auto-fallback, token compression và điều khiển qua MCP/A2A phía sau một endpoint local duy nhất.
Code Review Graph Explained: Review AI Thông Minh Hơn, Tốn Ít Token Hơn
Hướng dẫn cho người mới về code-review-graph: cách build graph cục bộ, giảm token khi review, và giúp AI assistant hiểu impact rõ ràng hơn.
i-have-adhd: Skill AI Nhỏ Khiến Coding Agent Cuối Cùng Cũng Trả Lời Thẳng
Hướng dẫn dễ hiểu về i-have-adhd, skill AI đang viral giúp Claude, Cursor, Copilot và Gemini trả lời thẳng thay vì vòng vo.