Đừng đốt token vào code exploration nữa: tối ưu Claude Code với CodeGraph

Nếu bạn đã dùng Claude Code thật sự lâu trên một codebase lớn, bạn sẽ thấy cảnh này. Bạn hỏi một câu tưởng đơn giản — "extension host giao tiếp với main process như thế nào?" — và Claude tung ra một Explore agent bắt đầu grep, glob, ls, và Read qua hàng chục file. Một rưỡi phút sau bạn có câu trả lời tốt, nhưng bạn cũng vừa đốt hết 90k token và 50 tool call để đến đó.

CodeGraph là một dự án open-source tấn công thẳng vào vấn đề này. Thay vì để Claude khám phá lại cấu trúc codebase từ đầu với mỗi câu hỏi, nó xây dựng một knowledge graph đã được pre-index sẵn từ code của bạn và đưa cho Claude thông qua một MCP server. Lời chào hàng thẳng thắn và có số liệu đi kèm: ít hơn 94% tool call, nhanh hơn 77% khi exploration, 100% chạy local.

Đây là cách nó hoạt động và cách cài đặt.

Vấn đề cốt lõi: exploration rất tốn kém

Khi Claude Code cần hiểu một phần của codebase, nó không có bản đồ. Nó tự xây bản đồ trong lúc chạy. Điều đó có nghĩa là phần lớn việc mà một Explore agent làm thực ra không phải là trả lời câu hỏi của bạn — đó là khám phá. Tìm xem mọi thứ nằm ở đâu. List directory, grep tên symbol, đọc file để xác định file nào quan trọng, rồi mới đọc các file thực sự liên quan.

Mỗi bước đó là một tool call, và mỗi tool call trả về nội dung đổ vào context window. Trên một repository lớn, giai đoạn khám phá này chiếm hầu hết chi phí. Agent tiêu phần lớn ngân sách chỉ để định hướng bản thân trước khi có thể bắt đầu suy luận về đoạn code bạn hỏi.

Insight của CodeGraph là toàn bộ thông tin cấu trúc này — cái gì gọi cái gì, cái gì import cái gì, class nào kế thừa class nào — là tĩnh và có thể tính toán trước. Vậy thì tính một lần, lưu local, và để Claude query ngay lập tức thay vì phải xây lại từ đầu với mỗi request.

CodeGraph thực sự xây gì

Bên dưới, CodeGraph dùng tree-sitter để parse source code thành abstract syntax tree, rồi chạy các query theo từng ngôn ngữ để rút ra hai thứ: node và edge. Node là các symbol — function, class, method. Edge là quan hệ giữa chúng — call, import, kế thừa, implement interface.

Tất cả được đưa vào một SQLite database local trong thư mục .codegraph/ của project, với FTS5 full-text search để tra cứu symbol gần như tức thì. Sau lần extraction đầu tiên, CodeGraph chạy một bước resolution nối các điểm lại: function call được liên kết với definition của nó, import với source file, class với class cha, v.v.

Kết quả là một graph có thể query được về ngữ nghĩa của codebase. Khi Claude muốn biết cái gì gọi login(), nó hỏi graph và nhận câu trả lời trong một call thay vì phải grep toàn bộ repo.

Quan trọng là graph tự cập nhật. CodeGraph chạy một file watcher được xây trên OS native event — FSEvents trên macOS, inotify trên Linux, ReadDirectoryChangesW trên Windows — với một quiet window hai giây debounce. Khi bạn sửa code, nó tự đồng bộ lại các phần bị ảnh hưởng theo từng bước nhỏ. Không có bước re-index thủ công trong luồng làm việc bình thường và không cần canh chừng cấu hình gì cả.

Số liệu benchmark

Dự án đã test Explore agent của Claude Code trên sáu codebase thực tế, chạy cùng một câu hỏi có và không có CodeGraph. Kết quả là tính năng nổi bật nhất, và đáng để xem kỹ vì mức tăng không hề nhỏ.

Trên codebase VS Code (4.002 file, ~59k graph node), để trả lời câu hỏi "extension host giao tiếp với main process như thế nào?", CodeGraph dùng 3 tool call và mất 17 giây. Không có nó, cùng câu hỏi đó cần 52 tool call và 1 phút 37 giây — giảm 94% số call và nhanh hơn 82%.

Pattern này lặp lại trên mọi ngôn ngữ được test. Trên Excalidraw (TypeScript): 3 call so với 47. Trên một codebase Java, một CodeGraph call duy nhất trả lời toàn bộ câu hỏi trong khi baseline cần 26. Trên Alamofire (Swift), CodeGraph trace một call chain 9 bước từ Session.request() xuống URLSession.dataTask() chỉ trong một explore call. Ngay cả target lớn nhất — Swift compiler với 25.874 file và 272.898 node — cũng được trả lời trong 6 call và 35 giây với zero file read, sau khi index xong trong chưa đầy bốn phút.

Hai nhận xét từ các lần chạy test nổi bật lên. Thứ nhất, với CodeGraph thì agent không bao giờ fallback sang đọc file — nó tin tưởng hoàn toàn vào kết quả từ graph. Thứ hai, không có CodeGraph thì agent tiêu phần lớn thời gian vào các lệnh discovery trước khi có thể đọc bất cứ thứ gì liên quan. Đó chính xác là sự lãng phí mà CodeGraph loại bỏ. Tổng hợp trên cả sáu codebase, trung bình ít hơn khoảng 92% tool call và nhanh hơn 71%.

Một lưu ý công bằng: các benchmark này đến từ chính dự án, chạy trên một phiên bản Claude Code và model cụ thể, với một Explore agent mỗi câu hỏi. Kết quả của bạn sẽ khác nhau tùy vào kích thước repo, loại câu hỏi, và cách code được tổ chức. Nhưng cơ chế là đúng, và hướng tác động khó mà tranh cãi — một index được tính toán trước thắng live discovery cho loại câu hỏi cấu trúc mà exploration agent xử lý.

Cài đặt và chạy

Setup thực sự chỉ mất vài phút. Interactive installer tự làm cấu hình cho bạn:

npx @colbymchenry/codegraph

Installer đề nghị cài CodeGraph globally (cần thiết cho MCP server), wire MCP server vào ~/.claude.json, thiết lập auto-allow permission cho các CodeGraph tool, và thêm hướng dẫn sử dụng vào global ~/.claude/CLAUDE.md của bạn. Sau khi xong, restart Claude Code để MCP server load lên.

Sau đó, trong mỗi project bạn muốn index:

cd your-project
codegraph init -i

Khi đã có thư mục .codegraph/, Claude Code tự nhận các tool. Đó là toàn bộ vòng lặp.

Nếu bạn muốn tự cấu hình bằng tay, cài globally với npm install -g @colbymchenry/codegraph rồi thêm server vào ~/.claude.json:

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

CodeGraph hỗ trợ 19+ ngôn ngữ với full support, bao gồm TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, và Pascal/Delphi.

Usage pattern quan trọng nhất

Đây là phần nhiều người bỏ qua, và đây là sự khác biệt giữa CodeGraph có ích và CodeGraph âm thầm gây hại. Các tool trả về các đoạn source lớn — codegraph_explore và codegraph_context — không nên được gọi trực tiếp trong session Claude Code chính của bạn. Chúng trả về nhiều source code, và đổ đống đó vào context chính là đi ngược lại mục đích. Cách đúng là để Claude spawn một Explore agent cho bất kỳ câu hỏi kiểu "X hoạt động như thế nào", và để agent đó dùng CodeGraph là tool chính. Hướng dẫn global của installer mã hóa quy tắc này, đó là lý do tại sao chạy installer thay vì tự cấu hình tay là đáng làm.

Session chính vẫn có thể dùng trực tiếp các tool nhẹ cho các tra cứu có mục tiêu ngay trước khi sửa:

Nhóm cuối đó chỉ ra một use case vượt ra ngoài exploration: an toàn khi thay đổi. Trước khi refactor một function, hỏi codegraph_impact về toàn bộ impact radius của nó sẽ cho bạn biết những gì bạn sắp động tới — mà không cần Claude phải grep codebase để tìm ra. Ngoài ra còn có một CLI command codegraph affected trace import dependency để tìm ra file test nào bị ảnh hưởng bởi một thay đổi, rất phù hợp để cắm vào pre-commit hook hoặc bước CI để chỉ chạy các test liên quan.

Có đáng không?

Nếu bạn chủ yếu dùng Claude Code trên các project nhỏ mà exploration vốn đã rẻ, CodeGraph là overkill — chi phí discovery mà nó loại bỏ vốn đã nhỏ. Lợi ích tỷ lệ thuận với kích thước codebase và tần suất bạn yêu cầu Claude suy luận về các phần không quen thuộc của hệ thống. Trên một repository lớn, đa ngôn ngữ mà bạn và Claude duyệt qua hàng chục lần một ngày, việc cắt chi phí exploration ~90% tích lũy nhanh, cả về latency lẫn token.

Nó cũng hoàn toàn local. Graph sống trong SQLite trên máy bạn, không có API key nào, và không có code nào rời khỏi môi trường của bạn — điều này quan trọng nếu bạn đang làm việc trên bất cứ thứ gì không thể gửi lên service của bên thứ ba. Với một tool miễn phí, MIT-licensed, cài trong vài phút, rủi ro downside thấp và upside trên đúng loại project là đáng kể.

Tóm lại một cách thành thật: CodeGraph không phải phép màu, đó là preprocessing. Nó di chuyển chi phí hiểu cấu trúc codebase của bạn từ "mỗi câu hỏi, tại runtime" sang "một lần, trước đó, rồi cập nhật dần dần." Với Claude Code trên một codebase nghiêm túc, đó chính xác là nơi đúng để di chuyển nó.

---

CodeGraph là open source theo MIT license. Tìm nó tại github.com/colbymchenry/codegraph.

Happy coding : )