1. 工具介绍

Codegraph 是一个本地代码知识图谱工具，专门给 AI agent 用的。
核心功能：把代码库解析成图结构（符号是节点，调用/依赖关系是边），存在本地 SQLite 里，然后通过 CLI 或 MCP 协议暴露给 agent 查询。
支持语言：Python、Java、TypeScript、Go 等主流语言都能解析。

对于 claude code 这类编码 agent 的实际价值：

• 减少幻觉 — agent 不再靠猜代码结构，而是查真实的图数据
• 节省上下文 — 不用把整个代码库塞进 prompt，按需查询相关片段
• 避免改坏东西 — 改之前先查影响范围，知道要一起改哪些测试和调用方
• 理解遗留代码 — 面对不熟悉的代码库，能快速理清调用链和依赖关系

安装

npm install -g @colbymchenry/codegraph --registry https://registry.npmmirror.com, 使用国内源, 更迅速.
装好后的位置示例: ~/.nvm/versions/node/v24.18.0/bin/codegraph.

2. 用法及示例

主要命令：

init / index — 建索引
sync — 增量更新
query — 搜索符号
callers / callees — 查调用关系
explore — 一次性看源码 + 调用链 + 影响范围
impact — 分析改某个符号会影响哪些代码
affected — 找受影响的测试文件

3. 真实项目示例

某项目, 建完索引后, 会得到 .codegraph/codegraph.db 文件. 利用统计功能可以看:

CodeGraph Status

Project: /Users/yichudu/code_work/xx

Index Statistics:
  Files:     771
  Nodes:     20,406
  Edges:     35,840
  DB Size:   55.41 MB
  Backend:   node:sqlite — built-in (full WAL)
  Journal:   wal

Nodes by Kind:
  import          8,238
  method          5,411
  field           3,425
  file            761
  namespace       723
  class           707
  enum_member     610
  constant        422
  enum            58
  interface       21
  function        20
  variable        10

Files by Language:
  java            724
  xml             36
  properties      5
  yaml            5
  python          1

✓ Index is up to date

4. demo示例

查看索引

它是标准的 sqlite3 索引, 可以直接 select 验证.

查看调用关系

继续执行 SELECT * FROM edges LIMIT 10;.
得到:

(base) yichudu@yichumacbookair cg-demo % /usr/bin/sqlite3 ./.codegraph/codegraph.db "SELECT * FROM edges LIMIT 10;"

1|file:src/Logger.java|class:eb9696a85f1d51e6cfc23212d3bd6543|contains||||
2|class:eb9696a85f1d51e6cfc23212d3bd6543|method:4768bf7673844a5fec20e4ae4f6989c3|contains||||
3|file:src/User.java|class:89e1ddb5e0719a82e1de008802f4c305|contains||||
4|class:89e1ddb5e0719a82e1de008802f4c305|field:3d1b9111729baeb1f37d982b4af9fa09|contains||||

Callees 查看主动调用

demo源码

// 另有 Logger.java 和 User.java, 篇幅所限做省略.
public class UserService {
    private final Logger logger = new Logger();

    public User findUser(String id) {
        logger.log("Finding user: " + id);
        return new User(id, "Alice");
    }

    public boolean deleteUser(String id) {
        User user = findUser(id);
        if (user != null) {
            logger.log("Deleting user: " + user.getName());
            return true;
        }
        return false;
    }
}