GitNexus: tấm bản đồ trên trình duyệt cho mọi repo

TL;DR

GitNexus xử đúng cái cảnh agent sửa một file mà không thấy import chain, call chain với vùng ảnh hưởng, nên vá xong chỗ này lại thủng chỗ khác.
Chuyện đó đáng lo vì khi đã giao việc cho Claude Code, Cursor, Codex hay Windsurf, cái giá của ngữ cảnh thiếu không còn là một bug lẻ mà là cả pull request đi lạc.
Nó hợp nhất với người đã có workflow local, hay nhận repo lạ, cần hỏi kiến trúc trước khi rename, refactor hay review thay đổi.
Use case mạnh nhất là index codebase một lần rồi dùng query, context, impact hoặc web UI để lần ra dependency và blast radius trước khi chạm tay vào code thật.
Điểm khác là GitNexus không quăng graph thô cho model tự bơi, mà gom sẵn quan hệ, cluster và execution flow để câu trả lời có cái sườn tử tế hơn.

GitNexus, tờ bản đồ còn mùi mực

Tôi gặp cảnh này hoài: mở một codebase lạ, tab browser chồng như chén bát sau đám cưới, agent thì trả lời rất tự tin, còn mình nhìn UserService với AuthMiddleware như nhìn hai ông bà con xa ở đám giỗ, quen mặt mà không dám nhận họ.

Có những tool đọc code kiểu cầm đèn pin đi trong hẻm, rọi tới đâu biết tới đó. GitNexus lại muốn làm kiểu trải cả tờ bản đồ lên bàn, thấy luôn ngõ cụt ở mô, đại lộ thông ở mô, chỗ nào đụng vô là cả xóm phải thức dậy. Repo này mở cửa bằng web UI, CLI và MCP, nên nhìn ngoài dễ tưởng đây chỉ là món để kéo thả ZIP rồi ngắm graph cho vui.

Nhưng có một chữ ngắn ngủn làm tôi khựng lại: serve.

Khi agent biết đường, nó bớt làm liều

Chữ serve nhỏ vậy thôi mà nó lộ ruột của món này. GitNexus không phải chatbot khoác thêm prompt dễ thương, mà là pipeline đi từ cây thư mục, parse AST bằng Tree-sitter, resolve import, call, inheritance rồi gom tiếp cluster với execution flow trước khi nạp vào LadybugDB.

Nói cho đời thường, thứ nó bán không phải câu trả lời mà là phần xương sống để câu trả lời đứng thẳng. README mô tả hướng này là precomputed relational intelligence. Hiểu nôm na, thay vì bắt model làm thám tử ngay lúc đang trả lời, nó chuẩn bị sẵn hồ sơ, sơ đồ và dây mơ rễ má từ trước.

Chuyện này trúng đúng nỗi đau bây giờ. Model thì thiếu gì, thiếu là lớp hiểu kiến trúc đủ sâu để agent khỏi sửa kiểu nhắm mắt chạy xe máy qua ngã tư. Một thay đổi đụng file nào, service nào gọi ngược lên, rename có kéo trúng góc khuất nào không, mấy câu đó mà không trả lời trước thì phần còn lại chỉ còn trông vào hên xui.

GitNexus cũng không ép bạn đi một cửa duy nhất. Có CLI để index và hỏi nhanh, MCP server cho agent gọi tool, HTTP bridge cho web UI, rồi browser mode để khám phá gấp khi chưa muốn cài nặng. Nhưng cửa càng nhiều thì câu hỏi càng gắt: ngày đi làm thật, nên bước qua cửa nào trước?

Real-World Use Cases

Chính cái câu hỏi đó mới đáng tiền. Repo này không hợp kiểu “tool cho mọi developer”, nó hợp ở mấy cảnh rất cụ thể, nghe xong là hình dung ra ngay.

Ngồi quán cà phê, khách quăng qua một repo lạ cần demo gấp, bạn kéo ZIP vào browser mode để xem graph trước khi dám nói “để em sửa được”.
Team đang họp PR review, có người muốn đổi tên một symbol quan trọng, bạn chạy impact analysis trước để khỏi merge xong mới thấy blast radius nở như bắp rang.
Làm freelance, nhận bàn giao một đống service, bạn cần query liên repo hoặc theo group để biết service nào đang dính contract với service nào.
Dùng Claude Code hoặc Cursor mỗi ngày, bạn muốn agent có ngữ cảnh tốt hơn thay vì mỗi lần hỏi lại thấy nó mò đường như người mới xuống bến xe.
Cần dựng code wiki từ quan hệ đã phân tích sẵn, khỏi ngồi viết tài liệu từ đầu rồi tháng sau chẳng ai dám cập nhật.

Một vòng chạy kiểu thực chiến nhìn như ri:

$ cd /path/to/repo
$ npx gitnexus analyze
# parse codebase, dựng graph, đăng ký repo vào local registry

$ npx gitnexus status
# kiểm tra codebase đã được index chưa

$ npx gitnexus query "authentication flow" --repo MyRepo
# trả về node, relation và ngữ cảnh liên quan tới luồng auth

$ npx gitnexus impact UserService --direction upstream --repo MyRepo
# lần ra chỗ nào gọi ngược về UserService để ước lượng vùng ảnh hưởng

$ npx gitnexus serve
# bật local bridge để web UI dùng lại index sẵn có

Cảnh tôi thấy đã nhất là trước một thay đổi hơi nhạy. Ví dụ bạn định sửa UserService mà chưa chắc tầng nào đang đụng tới nó. Thay vì mở rg, nhảy file rồi tự nối dây trong đầu như thợ điện không có sơ đồ, bạn hỏi thẳng lớp phân tích đã dựng sẵn. Nó không quyết thay bạn, nhưng nó kéo quyết định ra khỏi vùng đoán mò.

Nếu bạn đang sống trong workflow agent mỗi ngày, có thể đọc thêm Claude Code Missing Manual và Claude Skills: The Surgical Agent. Hai bài đó không nói về GitNexus, nhưng lại chạm đúng chỗ agent thường làm liều khi thiếu ngữ cảnh.

Usages

Nhìn xuống bề mặt dùng mới thấy GitNexus không chỉ có một lệnh đẹp mắt. Mỗi cửa vào đổi luôn cái giá bạn phải trả.

Lệnh đáng chú ý nhất vẫn là analyze. Nó duyệt codebase, parse code, resolve quan hệ, tạo graph local rồi đăng ký repo vào registry toàn cục. Research cũng ghi rõ một chi tiết dễ quên: nếu đã từng tạo embeddings, những lần analyze sau vẫn nên truyền lại cờ embeddings nếu không muốn phần đó bị bỏ.

setup là cửa tiện nhất cho editor integration, nhưng cũng là cửa nên đọc kỹ nhất. Docs nói rõ lệnh này tự phát hiện editor rồi ghi cấu hình MCP toàn cục trong thư mục người dùng. Nó không chỉ sửa trong repo hiện tại.

serve là cây cầu giữa lớp local đã index với web UI. Chạy lệnh này rồi mở giao diện web, browser có thể phát hiện local server và duyệt các repo đã có sẵn mà không cần upload hay lập chỉ mục lại.

Mấy tool call mà repo minh họa cũng nói lên cách họ nghĩ:

impact({ target: "UserService", direction: "upstream", minConfidence: 0.8 })

query({ query: "authentication middleware" })

rename({ symbol_name: "validateUser", new_name: "verifyUser", dry_run: true })

impact trả về vùng ảnh hưởng để bạn biết sửa một chỗ thì kéo theo chỗ nào. query tìm theo ý định kiến trúc thay vì chỉ text match. rename có dry_run, nghĩa là chuyện refactor được xem như đo trước rồi mới cắt, chứ không phải bổ một nhát rồi ngồi chắp tay.

💡 Tip: Nếu bạn chỉ cần coi nhanh một codebase, browser mode đủ xài. Nếu bạn muốn nhét GitNexus vào workflow hằng ngày, nên nghĩ theo hướng index local một lần rồi dùng CLI, MCP hoặc bridge trên cùng lớp dữ liệu.

⚠️ Warning: analyze có thể cài skill, hook cho agent và tạo file context trong repo. setup còn ghi cấu hình MCP toàn cục. Đừng chạy mù trên máy chính nếu bạn ghét phần mềm tự vào nhà rồi tự đổi chỗ tủ.

Bề mặt dùng đã rõ, nhưng vì sao mấy cửa khác nhau đó vẫn nói cùng một thứ tiếng thì phải nhìn xuống phần ruột.

How It Works Under the Hood

Phần ruột của GitNexus không màu mè lắm, chỉ là làm việc khá chăm. Luồng chính trong repo đi theo nhịp này:

repo files
   |
   v
tree walk
   |
   v
Tree-sitter parse
   |
   v
resolve import / call / inheritance / receiver type
   |
   v
community + process detection
   |
   v
LadybugDB graph store + local repo registry
   |                    |
   |                    +--> MCP server cho agent
   |                    +--> HTTP bridge / local server
   |
   +------------------------> web UI browser mode hoặc server-backed mode

Điểm đáng nói không phải chỉ là “có graph”. Nhiều tool cũng nói câu đó. Chỗ GitNexus khác tay nằm ở việc nó gom sẵn quan hệ kiến trúc và execution flow trước khi đưa ra ngoài, nên context, impact hay query có cơ hội bám vào cấu trúc đã được chuẩn bị, thay vì bắt model vừa nghĩ vừa tự vẽ sơ đồ trên khăn giấy.

Breadcrumb ở đầu bài nằm ngay đây. Web UI đúng là chạy được trong browser, kể cả kiểu kéo thả ZIP để khám phá nhanh. Nhưng browser mode chỉ là mặt tiền nhẹ. Khi bạn bật serve, local server dùng chung backend để xuất REST với MCP-over-HTTP, còn web UI chuyển sang ăn lại index local đã có. Thành ra chuyện “trên trình duyệt” là thật, nhưng phần nặng ký lại nằm ở phía bridge trên máy bạn.

Thiết kế đó khá tỉnh. Nó cho người mới bước vào bằng cửa browser-only, nhưng không tự trói mình ở đó. README cũng nói rõ mode này hợp khám phá nhanh và bị giới hạn bộ nhớ khoảng 5.000 file. Qua mốc đó mà còn cố, tờ bản đồ đang phẳng đẹp sẽ biến thành cuộn giấy nhăn giữa cơn mưa.

Nhưng hễ đã có local registry, graph store, server loopback và editor integration thì câu hỏi kế tiếp không còn là kiến trúc nữa. Nó là ranh giới tin cậy.

Security Review

Trust boundary của GitNexus rộng hơn vẻ ngoài nhiều. Đây không phải package chỉ đọc codebase rồi thôi.

Phần yên tâm trước đã: research không thấy eval(, new Function, payload base64 hay kiểu curl | bash đáng ngờ trong package scripts chính. Clone có chặn URL private hoặc internal, local server mặc định bind vào loopback và CORS bị giới hạn. Workflow AI đúng là vùng nhạy cảm, nhưng repo có kiểm tra author_association, checkout theo head SHA và đa số action được pin theo commit SHA.

Phần cần nhìn kỹ cũng rõ như ban ngày:

setup tự phát hiện editor và ghi cấu hình MCP toàn cục trong thư mục người dùng.
analyze có thể cài agent skills, đăng ký hook cho Claude Code và tạo thêm file context trong repo.
Package CLI có prepare và prepack chạy build script cục bộ.
Có optional dependency kéo trực tiếp từ GitHub commit cho tree-sitter-dart, nên bề mặt supply-chain không nằm trọn trong registry.
Có local server, local index và local registry, nghĩa là trạng thái được giữ lại trên máy chứ không phải đóng tab là sạch.
Workflow triage có quyền ghi issue hoặc PR và cài dependency Python trong runner.

Mức rủi ro hợp lý nhất là trung bình. Tôi vẫn dùng được, nhưng chỉ sau khi đọc kỹ mấy lệnh đụng config, hook và automation. Không phải ai cũng thấy cái giá đó đáng trả.

Who Should Use It (And Who Should Skip It)

Chính chỗ “đáng trả hay không” mới chia người dùng ra rõ nhất. Nếu nỗi đau của bạn là agent thiếu bản đồ kiến trúc hơn là thiếu model, GitNexus trúng đối tượng.

Nó hợp với dev đang dùng Claude Code, Cursor, Codex, Windsurf hay OpenCode mà cứ bực vì agent nhìn dependency như nhìn sương sớm. Nó cũng hợp cho team cần blast radius analysis, symbol context, query liên repo hoặc muốn sinh code wiki từ lớp quan hệ đã phân tích sẵn. Với người hay onboarding một codebase lạ, việc có browser mode để ngó nhanh rồi chuyển qua CLI hoặc MCP cho công việc thật là một lối vào khá mượt.

Nhưng có vài nhóm nên né sớm cho đỡ mất công:

Người cần license permissive để dùng thương mại ngay từ bản OSS. License ở đây là PolyForm Noncommercial 1.0.0.
Người không chấp nhận tool ghi config MCP toàn cục, cài hook cho agent hay tạo file context.
Team muốn mọi thứ chạy thuần browser trên codebase lớn.
Người ghét local hidden index, local registry và thêm một service chạy trên máy.
Ai kỳ vọng repo công khai này đã bao trọn toàn bộ offering thương mại hoặc self-hosted.

Nói ngắn gọn, nó dành cho người chấp nhận thêm một lớp hạ tầng nhỏ trên máy để đổi lấy ngữ cảnh sâu hơn. Nếu bạn đúng nhóm đó, cách thử hợp lý nhất lại không nằm ở màn demo bóng bẩy.

Getting Started

Đường ngắn nhất tới kết quả thật là lấy một repo bạn đang sửa dở, đừng lấy repo đồ chơi.

Đảm bảo máy có Node.js 20+ và git.
Vào codebase đích rồi chạy npx gitnexus analyze.
Kiểm tra trạng thái bằng npx gitnexus status hoặc npx gitnexus list.
Hỏi đúng chỗ đang đau nhất, kiểu npx gitnexus query "authentication flow" --repo MyRepo.
Nếu muốn agent dùng được lớp ngữ cảnh này, mới tính tiếp tới npx gitnexus setup.
Nếu thích nhìn bằng giao diện web nhưng không muốn phân tích lại từ đầu, bật npx gitnexus serve.

Nếu bạn đi từ source của chính repo này thì docs ghi khá thẳng: build package shared trước, rồi package web, sau đó npm run dev. Còn nếu chỉ cần dùng tool, npm install -g gitnexus hoặc npx là đủ để mở màn.

Đừng lấy browser-only làm bài test đầu cho codebase to. README ghi rõ mode này hợp khám phá nhanh và bắt đầu đuối quanh mốc 5.000 file. Với repo lớn, backend mode đỡ mệt đầu hơn. Embeddings cũng là con dao hai lưỡi vì docs nói rõ nó chậm hơn, ăn RAM và disk nhiều hơn, thậm chí có thể bị skip hoặc limit trên codebase lớn.

💡 Tip: Lần đầu cứ analyze không embeddings trước cho quen nhịp. Khi nào thấy query thường xuyên thiếu độ sâu semantic thì mới bật thêm, kẻo ngồi chờ rồi tưởng laptop mình sắp hóa lò sưởi.

Nhưng thử xong mà thấy không hợp thì cũng bình thường thôi. Có loại bản đồ sinh ra để treo tường, có loại để nhét cốp xe rồi đi thật.

How It Compares: Alternatives

Cái “đi thật” hay không thường lộ ra rõ nhất lúc đem so với thứ khác. Repo này có nhắc đích danh DeepWiki, Traditional Graph RAG và chuyện cấu hình MCP thủ công, nên so tới đó là vừa.

Cách tiếp cận	Hợp nhất khi nào	Điểm GitNexus cố làm khác	Khi nào nên chọn bên kia
DeepWiki	Bạn cần hiểu code nhanh theo kiểu đọc wiki và nắm bức tranh lớn	Đi sâu hơn vào relation, impact, context và tool surface cho agent	Chọn DeepWiki nếu nhu cầu chính là hiểu nhanh, ít cần blast radius hay workflow local
Traditional Graph RAG	Bạn đã có graph store và chấp nhận để model tự truy nhiều bước	Precompute nhiều cấu trúc hơn, gom sẵn relation và flow trước khi trả kết quả	Chọn cách này nếu bạn thích pipeline mở và muốn tự điều khiển retrieval
Manual MCP configuration	Bạn muốn editor integration nhưng không muốn lệnh tự sửa config	Có `setup` để bớt công lắp tay	Chọn manual nếu bạn rất kỹ chuyện config toàn cục và muốn tự giữ từng con ốc

Nếu bạn thích đọc thêm về kiểu agent orchestration và bề mặt điều phối quanh CLI, Claude Code Orchestration Mastery là bài liên quan hơn mấy bài marketing ngoài kia. Còn nếu chỉ hỏi “cái nào hay hơn” thì thường đang hỏi sai câu.

FAQ

GitNexus có phải một IDE mới không?
Không. Research cho thấy nó là lớp code intelligence mở ra qua CLI, MCP, HTTP bridge và web UI, chứ không tự định vị như một IDE thay thế editor hiện tại.
Có thể dùng chỉ trong browser không?
Có. Repo mô tả browser-only mode với kiểu kéo thả ZIP để khám phá nhanh, nhưng mode đó bị giới hạn bộ nhớ khoảng 5.000 file.
Dùng với Claude Code hay Cursor có hợp không?
Hợp nếu thứ bạn thiếu là ngữ cảnh kiến trúc, dependency và vùng ảnh hưởng trước khi agent sửa code.
Có nên chạy bừa trên máy chính không?
Tôi sẽ không làm rứa. setup ghi config MCP toàn cục, còn analyze có thể cài hook, skill và tạo file context.
Có hợp cho commercial use ngay từ bản OSS không?
Không phải kiểu cầm lên dùng khỏi nghĩ. License là PolyForm Noncommercial 1.0.0, nên ai có nhu cầu thương mại phải soi kỹ phần license trước.

Mà thường quyết định ở lại lâu hay không không nằm ở FAQ. Nó nằm ở lần đầu bạn hỏi một câu khó và tool có chỉ đúng ngõ hay không.

Final Thoughts

Tôi vẫn quay lại hình ảnh tờ bản đồ trên bàn. Loại bản đồ tốt không làm mình thành tài xế giỏi hơn trong một đêm, nhưng nó ngăn mình rẽ bậy ở cái ngã tư mà đáng ra không nên ngu tới mức đó.

GitNexus cũng vậy. Nó không hứa agent sẽ hết ngáo. Nó chỉ cố thêm xương sống vào chỗ lâu nay toàn cơ bắp với niềm tin, mà thú thiệt, dân từng fix bug lúc một giờ sáng thường cần cái đó hơn là một màn demo bóng loáng.

Tôi vốn dị ứng với việc phải nuôi thêm service trên máy. Quạt laptop đã gào đủ rồi. Nhưng tôi còn dị ứng hơn với cảnh model đổi tên một symbol như người thợ cắt tóc không soi gương phía sau. Nếu tuần sau tôi vẫn quay về grep với sơ đồ chắp vá trong đầu, chắc không phải vì GitNexus dở, mà vì cái tính tôi còn nghèo kiên nhẫn hơn cả RAM máy.

Thiệt ra repo.hoangyell.com cũng mang ơn GitNexus một phần. Hồi tôi còn viết bài GitNexus Explained trên blog chính, có bữa đồng nghiệp biết tin trước cả tôi. Họ bảo chỉ cần search gitnexus là đã thấy bài anh Yell nằm top 1 Google, nếu không tính GitHub. Nghe xong đã tai gì đâu. Tôi nghĩ bụng thôi, đúng long mạch rồi, phải đầu tư cái ngách này cho ra hồn. Thế là repo.hoangyell.com ra đời như một lời chào đàng hoàng với thế giới.