GitNexus: "Hệ thần kinh" cho AI Agent khi làm việc với codebase lớn
Nếu bạn từng để Cursor, Claude Code hay Codex sửa một hàm rồi phát hiện làm gãy 5 chỗ khác — GitNexus là giải pháp knowledge graph AST cục bộ giúp AI nắm trọn cấu trúc codebase.
Nếu bạn đã từng để Cursor, Claude Code hay Codex sửa một hàm rồi phát hiện ra nó vừa làm gãy 5 chỗ khác mà chính bạn cũng không nhớ hết — bài viết này dành cho bạn. Hôm nay mình giới thiệu GitNexus, một dự án open-source đang rất hot trên GitHub (45k+ sao, nằm trong top Trendshift), giải quyết triệt để vấn đề đó.
Repository chính thức: github.com/abhigyanpatwari/GitNexus
1. Giới thiệu
GitNexus tự mô tả mình là "the nervous system for agent context" — tạm dịch: hệ thần kinh cho ngữ cảnh của AI agent. Về bản chất, đây là một công cụ:
- Index (quét & phân tích) toàn bộ codebase: Chuyển đổi repository thành một Knowledge Graph (đồ thị tri thức). Mọi dependency, call chain, cluster chức năng, luồng thực thi (execution flow) đều được ghi nhận chi tiết.
- Expose đồ thị qua MCP (Model Context Protocol): Chuẩn giao tiếp mở mà Claude Code, Cursor, Codex, Windsurf, Cline, Roo Code... đều hỗ trợ.
Hai cách tiếp cận linh hoạt:
- CLI + MCP (Khuyên dùng): Dành cho coding hàng ngày với Claude Code, Cursor, Codex... Không giới hạn kích thước repository, chạy hoàn toàn local trên máy tính, bảo mật tuyệt đối không gọi mạng.
- Web UI: Dùng để khám phá nhanh, demo đồ thị visual. Dùng trực tiếp trên gitnexus.vercel.app mà không cần cài đặt (giới hạn bởi RAM trình duyệt ~5k file).
Hỗ trợ 14 ngôn ngữ lập trình phổ biến: TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, C, C++, Dart — cực kỳ đầy đủ cho cả Web Frontend lẫn các kỹ sư Backend như Java / Spring Boot.
2. Tác dụng: Nó giải quyết vấn đề gì?
Vấn đề gốc của AI Coding hiện nay
Các coding agent hiện nay rất giỏi viết code cục bộ, nhưng chúng không thực sự hiểu cấu trúc toàn cục của codebase:
- AI sửa
UserService.validate(). - AI không biết có 47 hàm khác đang phụ thuộc vào giá trị trả về của hàm này.
- Breaking change được ship — và bạn chỉ phát hiện ra khi CI báo đỏ, hoặc tệ hơn là khi production báo lỗi runtime.
Cách khắc phục truyền thống là "Graph RAG" — đưa cho LLM một đống graph edge thô và hy vọng nó tự truy vấn đủ sâu. Nhưng cách này tốn rất nhiều lượt gọi (multi-query), tốn token, và mô hình nhỏ thường bỏ sót.
Giải pháp của GitNexus
GitNexus đi theo hướng khác: tính toán trước cấu trúc ngay tại thời điểm index (*precomputed relational intelligence*) — clustering, tracing, chấm điểm confidence — để khi agent gọi 1 tool, nó nhận về câu trả lời đã được cấu trúc hoàn chỉnh, thay vì phải tự dò từng bước.
So sánh: Trước và Sau khi sử dụng GitNexus
- Trước khi dùng GitNexus:
- Agent hỏi "cái gì phụ thuộc vào UserService?" → phải tự query nhiều lần: tìm caller → tìm file → lọc test → đánh giá rủi ro → mới ra câu trả lời (thường mất 4+ lượt gọi tool, tốn nhiều token, dễ bỏ sót).
- Agent không biết đổi 1 dòng code sẽ ảnh hưởng process nào, module nào.
- Model nhỏ (rẻ hơn) thường "mù" kiến trúc, dễ sửa sai.
- Sau khi dùng GitNexus:
- Agent gọi 1 tool duy nhất, ví dụ impact UserService upstream, nhận về ngay: 8 caller, 3 cluster liên quan, độ tin cậy >90% — chỉ trong 1 lần gọi.
- Trước khi commit, agent (hoặc bạn) có thể chạy detect_changes để biết chính xác diff vừa rồi ảnh hưởng tới process nào, mức rủi ro (risk level) ra sao.
- Vì phần "nặng" đã được tool xử lý sẵn, ngay cả model nhỏ/rẻ cũng có được cái nhìn kiến trúc đầy đủ — không cần model "khủng" mới hiểu đúng codebase.
Tóm lại: Nếu DeepWiki giúp bạn hiểu code, thì GitNexus giúp AI agent phân tích code — nó theo dõi từng mối quan hệ (relationship), không chỉ mô tả suông.
3. GitNexus cung cấp gì cho AI Agent?
Sau khi index, agent của bạn có quyền sử dụng:
17 MCP Tools mạnh mẽ:
query: Hybrid search (BM25 + semantic + RRF), gom theo process.context: Cho cái nhìn 360 độ về một symbol (ai gọi nó, nó gọi ai, nằm trong process nào).impact: Phân tích "blast radius" (sửa cái này thì vỡ những đâu).trace: Tìm đường đi ngắn nhất giữa 2 symbol.detect_changes: Map git diff vào các process bị ảnh hưởng, tính risk level.rename: Đổi tên symbol đa file, có graph-backed nên chính xác hơn find-replace thông thường.cypher: Query graph trực tiếp bằng ngôn ngữ Cypher.route_map,api_impact,shape_check: Dành riêng cho API và routing.
Agent Skills:
Tự động cài vào .claude/skills/: Exploring, Debugging, Impact Analysis, Refactoring, và cả bộ lệnh:
/gitnexus-plan/gitnexus-work/gitnexus-review/gitnexus-lfg(full pipeline: plan → work → review).
Hooks thông minh:
Với Claude Code và Codex, GitNexus cắm hook PreToolUse và PostToolUse để tự động bơm thêm graph context vào mỗi lần agent search, đồng thời cảnh báo khi index bị "stale" (cũ) sau khi bạn commit.
4. Cài đặt với Claude Code và Codex
Cách nhanh nhất (Tự động detect Editor)
Chạy 2 lệnh sau trong thư mục gốc của repository:
# 1. Index repo (chạy từ root của repo)
npx gitnexus analyze
# 2. Kết nối editor (chỉ cần 1 lần, tự detect Claude Code, Cursor, Codex...)
npx gitnexus setupanalyzesẽ index codebase, cài agent skills, đăng ký hook cho Claude Code, và tạo fileAGENTS.md/CLAUDE.md— tất cả trong 1 lệnh.setupsẽ ghi cấu hình MCP để agent dùng được graph.
Nếu chỉ muốn setup riêng cho Claude Code và Codex (bỏ qua các editor khác):
npx gitnexus setup -c claude-code,codexLưu ý cho ai dùng npm 11.x: npx có thể bị crash lúc cài (lỗi arborist của npm). Nếu gặp, dùng pnpm thay thế:
pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyzeHoặc cài global: npm install -g gitnexus@latest rồi chạy gitnexus analyze — cách này cũng giúp MCP khởi động nhanh hơn (bỏ qua bước resolve của npx).
Cài đặt thủ công cho Claude Code
# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp
# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcpClaude Code là editor được hỗ trợ đầy đủ nhất: MCP tools + skills + hook PreToolUse (bơm graph context vào search) + PostToolUse (phát hiện index cũ sau khi commit).
Cài đặt thủ công cho Codex
codex mcp add gitnexus -- npx -y gitnexus@latest mcpHoặc cấu hình qua file ~/.codex/config.toml (toàn hệ thống) hoặc .codex/config.toml (riêng project):
[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]Hoặc cài trọn gói dưới dạng Codex plugin (MCP + skills + hooks trong 1 bước):
codex plugin marketplace add abhigyanpatwari/GitNexus
# sau đó trong Codex: gõ /plugins -> cài "GitNexus"Lưu ý: Hook mới cài cần approve 1 lần qua `/hooks` trong Codex trước khi chạy. Chỉ nên chọn một trong hai cách cài (setup CLI hoặc plugin) để tránh hook chạy trùng 2 lần cho mỗi tool call.
5. Test thử: Một ví dụ thực tế
Giả sử bạn có một service Spring Boot (rất hợp với use case game analytics/Kafka mà nhiều bạn Java backend hay làm), sau khi index xong bạn có thể hỏi thẳng agent (Claude Code) những câu như:
1. Phân tích impact trước khi sửa code:
impact({target: "UserService", direction: "upstream", minConfidence: 0.8})Kết quả trả về dạng:
TARGET: Class UserService (src/services/user.ts)
UPSTREAM (những gì phụ thuộc vào class này):
Depth 1 (SẼ VỠ):
handleLogin [CALLS 90%] -> src/api/auth.ts:45
handleRegister [CALLS 90%] -> src/api/auth.ts:78
Depth 2 (CÓ THỂ BỊ ẢNH HƯỞNG):
authRouter [IMPORTS] -> src/routes/auth.ts2. Tìm hiểu một symbol từ mọi góc độ:
context({name: "validateUser"})→ Trả về file, dòng bắt đầu, ai gọi nó (incoming calls), nó gọi ai (outgoing calls), và nó thuộc process nào (VD: LoginFlow bước 2/7).
3. Kiểm tra trước khi commit:
detect_changes({scope: "all"})→ Trả về số symbol thay đổi, số process bị ảnh hưởng, và risk level (low / medium / high) — rất hữu ích để tự review trước khi push.
4. Query bằng Cypher nếu cần đào sâu:
MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn)
MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn)
WHERE r.confidence > 0.8
RETURN caller.name, fn.name, r.confidence
ORDER BY r.confidence DESCThử nghiệm nhanh bằng CLI:
Bạn có thể thử nhanh không cần cài vào editor nào — chỉ cần chạy các lệnh CLI tương ứng:
gitnexus query "authentication middleware"
gitnexus impact UserService --file src/services/user.ts
gitnexus trace validateUser createSession
gitnexus status # xem tình trạng index hiện tạiNếu muốn thử mà không đụng máy local, có thể vào thẳng gitnexus.vercel.app và dán link một repo GitHub public vào — Web UI sẽ dựng knowledge graph ngay trong trình duyệt, kèm chat AI để hỏi đáp về repo đó.
6. Một vài lưu ý khi triển khai thực tế
- Lưu trữ Index: Index được lưu tại
.gitnexus/trong từng repo (nên đưa vào.gitignore), và một registry toàn cục ở~/.gitnexus/registry.json— nhờ vậy một MCP server duy nhất phục vụ được nhiều repo cùng lúc, không cần cấu hình lại theo từng project. - Dự án lớn: Với repo lớn, nên bật
--embeddingsđể có semantic search tốt hơn (mặc định giới hạn an toàn 50.000 node). - Chế độ Read-Only: Có chế độ
GITNEXUS_MCP_READ_ONLY=1nếu muốn giới hạn agent chỉ được đọc, không cho phép các thao tác như rename hay raw Cypher — rất hợp lý khi triển khai cho team dùng chung. - Bảo mật tuyệt đối: Toàn bộ chạy local, không có network call nào từ CLI — phù hợp với các team có yêu cầu bảo mật code nghiêm ngặt.
7. Reference / Tài liệu tham khảo
- 🔗 Repo chính thức: github.com/abhigyanpatwari/GitNexus
- 🌐 Web UI (dùng thử không cần cài): gitnexus.vercel.app
- 🏛️ Kiến trúc chi tiết: ARCHITECTURE.md
- 🛠️ Vận hành & Troubleshooting: RUNBOOK.md
- 📖 Codex Hooks docs: developers.openai.com/codex/hooks
- 🔌 Model Context Protocol (MCP): modelcontextprotocol.io
- 💬 Discord cộng đồng: discord.gg/MgJrmsqr62
- 🏢 Bản Enterprise (SaaS / Self-hosted, PR review tự động): akonlabs.com
Tóm lại: Nếu bạn đang để AI agent tự động sửa code trên một codebase đủ lớn để không ai nhớ hết dependency, GitNexus là kiểu công cụ đáng thử — nó không thay AI viết code giỏi hơn, mà giúp AI biết mình đang đứng ở đâu trong cây phụ thuộc trước khi gõ phím.
💬 Bình luận (0)