GitNexus: CLI code intelligence cho AI agent
/GitNexus
GitNexus biến codebase mà AI agent sắp chỉnh sửa thành một knowledge graph, thay vì đống file mà agent phải grep mò mẫm. Cách tiếp cận tính sẵn cấu trúc này thực sự hơn hẳn việc nhét thẳng code thô vào prompt: một truy vấn impact trả về caller, cluster và điểm tin cậy chỉ trong một lần gọi thay vì cả chuỗi tìm kiếm dò dẫm, và ngay cả model nhỏ cũng xử lý được mà không bỏ sót dependency nào.
GitNexus thực chất là gì
GitNexus là công cụ index code nguồn thành knowledge graph: trỏ nó vào một git repo hoặc file ZIP, nó ánh xạ từng dependency, call chain, cluster và execution flow thành một graph có thể truy vấn được. GitNexus có bản CLI cài agent skills và MCP tools cho Claude Code, Cursor, Codex và các editor tương tự, cùng một Web UI riêng chạy thẳng trên trình duyệt tại gitnexus.vercel.app, không cần cài đặt gì cả.
Các tính năng chính
- ✓17 MCP tools (15 tool theo từng repo, 2 tool ở cấp group) gồm hybrid search (`query`: BM25 + semantic + RRF), phân tích blast-radius (`impact`), và dò đường đi ngắn nhất giữa hai symbol (`trace`).
- ✓`detect_changes` đọc một git diff và ánh xạ thẳng các dòng thay đổi vào những execution process bị ảnh hưởng, chứ không chỉ liệt kê file đã sửa.
- ✓Index PDG (program dependence graph) là tùy chọn, dựng bằng `gitnexus analyze --pdg`, thêm `explain` cho luồng taint từ source đến sink và `pdg_query` cho control/data dependence ở cấp câu lệnh.
- ✓Agent skills — Exploring, Debugging, Impact Analysis, Refactoring, Guide, CLI, cùng các skill quy trình Plan/Work/Review và pipeline đầy đủ LFG — tự cài vào `.claude/skills/`.
- ✓`gitnexus analyze --skills` chạy Leiden community detection để tìm các functional area của codebase và viết riêng một skill cho từng area.
- ✓Bridge mode (`gitnexus serve`) cho Web UI duyệt các repo mà CLI đã index sẵn, không phải upload lại.
- ✓Có sẵn tool `cypher` để truy vấn graph thô, cho những trường hợp các tool đóng gói sẵn không đáp ứng được.
- ✓10 MCP resource cung cấp thống kê repo, thành viên cluster, process trace và graph schema mà không cần gọi tool.
Cài đặt GitNexus
Đường cài chính thức là CLI: `npm install -g gitnexus`, hoặc chạy trực tiếp bằng `npx gitnexus analyze`. README nêu rõ hai vấn đề khi cài. Trên npm 11.x, `npx` có thể crash trước khi GitNexus kịp chạy, với lỗi `Cannot destructure property 'package' of 'node.target'` — một bug của chính arborist trong npm, không phải do GitNexus. Cách khắc phục là cài qua pnpm với `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`, hoặc cài global rồi bỏ qua `npx` hoàn toàn. Thứ hai, các tree-sitter grammar native thường build không cần C++ toolchain nhờ binary dựng sẵn, nhưng nếu máy không có `python3`/`make`/`g++`, đặt `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` trước khi cài sẽ bỏ qua đúng bốn grammar được vendor (Dart, Protocol Buffers, Swift, Kotlin) — các ngôn ngữ khác vẫn parse bình thường. Web UI thì không cần cài gì: mở gitnexus.vercel.app. Nơi lưu index cũng khác nhau theo chế độ: CLI lưu vào LadybugDB, storage engine riêng của dự án, còn Web UI giữ mọi thứ trong một instance WASM chạy trong bộ nhớ, mất luôn khi đóng tab.
Chạy analyze và setup
Chỉ cần hai lệnh, chạy từ thư mục gốc repo. `npx gitnexus analyze` index codebase, cài agent skills, đăng ký hook cho Claude Code, và tạo file context `AGENTS.md`/`CLAUDE.md` — tất cả trong một lượt chạy. `npx gitnexus setup` sau đó ghi cấu hình MCP cho những editor nó tự nhận diện — thu hẹp lại bằng `gitnexus setup -c cursor,codex` nếu chỉ muốn vài cái cụ thể. Vài flag đáng chú ý: `--branch` ghim index vào một branch cụ thể thay vì bám theo working tree, `--pdg` dựng index program-dependence-graph sâu hơn mà `explain` và `pdg_query` cần, còn `--skills` sinh ra các area skill riêng cho repo. `gitnexus serve` khởi động bridge mode để Web UI đọc được index do CLI dựng.
GitNexus phát huy tác dụng khi nào
- •Lần theo một call chain xuyên codebase lớn sau khi grep đã đuổi theo không kịp.
- •Chạy `detect_changes` trước khi commit để biết một diff thực sự chạm tới những execution process nào.
- •Đưa cho một model nhỏ, rẻ hơn đủ cấu trúc tính sẵn để khỏi cần bốn năm lượt tool call dò dẫm mới trả lời được "cái gì gọi tới hàm này".
- •Sinh tài liệu kiến trúc kèm mermaid diagram thẳng từ graph qua prompt `generate_map`.
- •Đổi tên nhiều file cùng lúc bằng tool `rename` hiểu graph, thay vì tìm-thay bằng text thuần.
Điểm làm tốt
- ✓Bề mặt MCP sâu bất thường so với nhóm công cụ cùng loại — 17 tool, 10 resource, 2 prompt, chứ không phải một endpoint search chung chung.
- ✓Claude Code và Codex có tích hợp hook PreToolUse/PostToolUse thật sự, không phải một MCP server gắn thêm cho có.
- ✓Chế độ CLI chạy hoàn toàn local. Không gọi mạng, không upload gì lên server bên thứ ba.
- ✓Hai lỗi cài đặt được tài liệu hoá kèm đúng chuỗi lỗi thật và cách khắc phục cụ thể, không phải kiểu "cài lại rồi cầu may".
Điểm còn vướng
- △npm 11.x có thể làm `npx` crash thẳng. Đây là trở ngại cài đặt có thật mà dự án phải tìm cách né, vì bug nằm ở tầng arborist của npm, không phải chỗ GitNexus sửa được.
- △Web UI giới hạn khoảng 5.000 file trong bộ nhớ trình duyệt, trừ khi ghép với một backend do CLI index qua bridge mode.
- △`explain` và `pdg_query` không chạy được với một lượt `gitnexus analyze` thông thường; chúng cần index `--pdg` riêng trước.
- △Việc parse Kotlin phụ thuộc vào một tree-sitter grammar được vendor và cross-build sẵn, không đảm bảo có bản prebuilt cho mọi platform-arch — nếu không khớp, file `.kt`/`.kts` sẽ âm thầm không được parse.
- △Ở bản deploy hosted trên Render, proxy loại bỏ header `Origin`, nên CSRF guard của server không áp dụng được cho traffic đi qua proxy — access token là lớp chặn thật sự duy nhất.
GitNexus so với các lựa chọn khác
GitNexus phù hợp với bạn nếu...
Hợp với một team đã dùng Claude Code, Cursor hay Codex trên một codebase đủ lớn để agent hay bỏ sót nơi gọi hàm hoặc đổi tên nửa vời — kiểu repo mà tự tay phân tích impact còn mất thời gian hơn cả việc sửa code. Một dev làm side project nhỏ một mình khó mà thấy được khác biệt; graph này đáng công sức bỏ ra khi câu hỏi "còn chỗ nào gọi tới cái này" không còn là thứ nhớ nổi trong đầu.
Câu hỏi thường gặp
CLI và Web UI của GitNexus dùng không mất phí — cài CLI qua npm hoặc mở Web UI tại gitnexus.vercel.app, README không nêu bước đăng ký nào. Dự án còn liệt kê một gói Enterprise riêng (SaaS và self-hosted) bên cạnh các công cụ miễn phí đó, nhưng không công bố giá cho gói này.
Chạy `npx gitnexus setup` sẽ tự nhận diện Claude Code, ghi cấu hình MCP, cài agent skills và đăng ký hook PreToolUse/PostToolUse trong một bước. Nếu muốn tự cấu hình, chạy `claude mcp add gitnexus -- npx -y gitnexus@latest mcp` để đăng ký riêng MCP server.
GitNexus parse code bằng tree-sitter — bản native binding trong CLI, bản WASM trong Web UI. README nêu đích danh bốn grammar được vendor và tùy chọn: Dart, Protocol Buffers, Swift và Kotlin, mỗi cái cần một bước build hoặc một bản prebuilt khớp nền tảng. Danh sách đầy đủ các ngôn ngữ còn lại không được công bố.
Trên npm 11.x, GitNexus có thể lỗi ngay trước khi kịp chạy: chạy qua `npx` sẽ crash với lỗi `Cannot destructure property 'package' of 'node.target'`, một bug nằm ở bộ giải arborist của chính npm. Cách khắc phục được nêu là cài qua pnpm với các flag `--allow-build` của dự án, hoặc chạy `npm install -g gitnexus` rồi gọi thẳng `gitnexus analyze` thay vì qua `npx`.
GitNexus không công bố mức RAM tối thiểu cho việc index qua CLI ở máy local, chỉ ghi rằng việc index bị giới hạn bởi bộ nhớ. Bản deploy Render của dự án cho một mốc tham khảo: gói server `standard` chạy 2 GB RAM, gói `pro` chạy 4 GB, và cách khắc phục khi repo lớn làm hết bộ nhớ là nâng gói lên.
Web UI của GitNexus tại gitnexus.vercel.app không cần cài đặt: mở lên rồi thả vào một git repo (GitHub, GitLab, Azure, hoặc local) hay một file ZIP. Bộ nhớ trình duyệt giới hạn khoảng 5.000 file; vượt quá mức đó, bridge mode (`gitnexus serve`) nối cùng Web UI này với một repo mà CLI đã index sẵn.
Repo liên quan
GitNexus có đáng để bạn bỏ thời gian?
ChatGPT, Claude và Perplexity đều đọc được trang này. Hỏi thử xem họ nghĩ gì về GitNexus.