你有没有这种感觉

打开 Claude Code，输入需求，然后……开始等。

Explore(Explore /src/api/ structure)
  Done (24 tool uses · 40.0k tokens · 59s)
Explore(Explore /src/components/ structure)
  Done (32 tool uses · 57.0k tokens · 1m26s)
Explore(Explore /src/database/ structure)
  Done (18 tool uses · 33.0k tokens · 51s)

60 次工具调用，157,800 个 token，将近 2 分钟 – 这还没开始干正事呢。

这感觉就像你每天打车上班，司机都要先把整条街开一遍"熟悉路况"，然后才送你到公司。你说你昨天不是刚走过这条路吗？司机摊手：不好意思，我失忆了。

Claude Code 就是这个失忆的司机。每开一次新会话，之前攒下的代码理解全清零，从头来过。关掉会话？学费白交。

今天介绍一个 token 优化工具，让这个司机随身揣着地图上路。

CodeGraph 是什么：给你的代码库画一张地图

CodeGraph 的思路很朴素：与其让 Claude Code 每次都盲人摸象，不如提前把代码库的"关系图"画好，存在本地数据库里。

它用 tree-sitter 解析你的源代码，提取出所有"有名有姓"的东西 – 函数、类、方法、接口、类型、变量，然后把它们之间的关系也理清楚：

  • 谁调用了谁（函数 A 调了函数 B）
  • 谁继承了谁（类 Dog 继承了类 Animal）
  • 谁实现了谁（UserService 实现了 IUserService 接口）
  • 谁引用了谁（文件 A import 了文件 B 的东西）

这些关系全存进本地 SQLite 数据库，还附带向量嵌入做语义搜索。说白了就是一张代码知识图谱。

打个比方：你的代码库是一座城市，Claude Code 之前靠步行逐条街道摸路线，现在 CodeGraph 直接给了它一张高德地图。

装上前 vs 装上后：真实数据说话

原文作者 Colby McHenry 在同一个项目上，用同样的复杂任务跑了 3 次对比：

指标没有 CodeGraph有 CodeGraph变化
Explore 阶段 Token~130k~69.4k减少约 30%
工具调用次数~74 次~56 次减少约 25%
探索耗时~2m16s~1m57s明显缩短

你可能觉得，30% 也没多少嘛。但这是每一次会话都要交的"过路费"。一天开 10 次会话，一周 5 天，一个月下来省掉的 token 够请自己吃好几顿饭了。

而且探索阶段越短，留给实际干活的上下文窗口就越大。上下文窗口就像你的工作台面 – 台面被地图铺满了，还怎么放材料干活？

5 分钟搞定安装

前提条件：Node.js 18+ 和 Claude Code。

第一步：运行安装器

npx @colbymchenry/codegraph

交互式安装器帮你搞定这几件事：

  1. 在 ~/.claude.json 里配好 MCP 服务器
  2. 设置 CodeGraph 工具的自动授权
  3. 问你要不要初始化当前项目

第二步：重启 Claude Code，然后初始化项目

codegraph init -i

作者的项目 85 个文件、542 个代码符号，索引+关系映射，半秒搞定。

第三步：没了

真的没了。Git hooks 会在每次提交时自动同步索引，不用你操心维护。

记住：npx @colbymchenry/codegraph 安装，codegraph init -i 初始化，git commit 自动更新。之后就忘了它的存在吧。

它到底做了什么（原理速写）

CodeGraph 干的事拆开看就四步：

CodeGraph 工作流程：解析、存储、连接、保鲜

1. 解析

用 tree-sitter 把源代码变成 AST（抽象语法树），从里面提取"节点"和"边"：

  • 节点：函数、类、方法、接口、类型、变量
  • 边：调用关系、导入关系、继承关系、实现关系、类型引用

2. 存储

所有信息存进本地 SQLite 数据库：

  • FTS5 全文搜索（按名字找）
  • 向量嵌入语义搜索（按意思找）
  • 图遍历（找关联关系）

3. 连接

通过 MCP（Model Context Protocol）暴露给 Claude Code。Claude 要理解代码时，直接查图谱，不用再挨个翻文件。

4. 保鲜

Git hooks 在每次 commit 后自动重新索引。代码变了，图谱跟着变。

一句话概括：先画地图，再查地图，地图自动更新。

跟"土法炼钢"比有啥不一样

CodeGraph 出来之前，大家已经想了不少法子对付"Claude Code 每次失忆"这事：

方案一：往 CLAUDE.md 里塞信息

把代码库结构、架构说明、文件列表写进 CLAUDE.md。Claude 启动时会读这个文件，相当于给它一张"手写笔记"。

问题是：笔记终究是笔记，Claude 只是在"读文档"，它并不真的理解代码之间的调用关系。你告诉它"UserService 在 src/services/ 下"，但它不知道 UserService 被哪 15 个地方调用了。

方案二：子代理+共享记忆文件

让探索代理把发现写进共享 markdown 文件，下次用。更精细了，但本质还是文本，还是缺少结构化的关系数据。

方案三：手动把相关代码贴进提示词

最笨但有效的方法 – 你直接告诉 Claude “看这段代码”。问题是不 scale，你不可能每次都手动找好代码再贴进去。

CodeGraph 和这些方案的根本区别：它给 Claude 的不是一份"参考资料"，而是一个可以直接查询的结构化数据库。就像笔记和数据库的区别 – 你能用 SQL 查笔记吗？

几个好用的能力

语义搜索

搜"authentication"，能找到 login、validateToken、AuthService，哪怕命名风格完全不同。比 grep 按字面匹配强不少。

影响分析

改一个函数之前，先问问它的"爆炸半径" – 谁调用了它？谁依赖它？改了会波及哪里？大型重构的时候特别管用。

16+ 语言支持

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin，甚至 Shopify 的 Liquid 模板语言都行。不挑食。

完全本地运行

不联网，不要 API Key，不依赖外部服务。就一个本地 SQLite 文件躺在你项目里。处理公司代码或敏感项目的人，应该会比较在意这一点。

踩坑提醒

坑一：大型 monorepo 初始化可能比较慢

作者的示例是 85 个文件半秒完成，但如果你的项目有几千个文件，首次索引会久一些。好消息是只需要跑一次，之后 git hooks 做增量更新。

应对：先用 .codegraphignore（如果支持）或者 .gitignore 排除 node_modules、dist、vendor 这些不需要索引的目录。

坑二：MCP 工具搜索的上下文开销

如果你已经配了不少 MCP 服务器，工具列表本身也占上下文。Anthropic 在 2026 年 1 月出了 MCP Tool Search 功能，能动态加载工具，把工具列表的 token 开销从 77K 压到 8.7K。MCP 装得多的话，建议一起开。

坑三：别忘了重启 Claude Code

安装完 MCP 服务器后，需要重启 Claude Code 才能生效。我知道这听起来像废话，但你一定会忘。

总结

  1. CodeGraph 用 tree-sitter 解析代码、SQLite 存关系图谱、MCP 对接 Claude Code，让探索代理查图谱而不是扫文件
  2. 实测减少约 30% 的 token 消耗和 25% 的工具调用，每次会话都在省钱
  3. 本地运行、Git hooks 自动更新、16+ 语言支持，装上就忘

可以复制的速查表：

# 安装
npx @colbymchenry/codegraph

# 初始化项目
codegraph init -i

# 手动重建索引（一般不需要，git hooks 会自动同步）
codegraph index

# 查看索引状态
codegraph status

你的 Claude Code 每次"认路"要花多少 token？

说真的，你可以留意一下自己每次开新会话时，Explore 阶段到底烧了多少 token。如果你的项目超过 100 个文件，大概率会被这个数字吓一跳。token 优化这件事，早晚得面对。

下一篇我们可以聊聊怎么把 CodeGraph 和 Context7（另一个能拉实时文档的 MCP 工具）搭配着用，让 Claude Code 不光认识你的代码，还能随时查最新的库文档。这也算是 Context Engineering 的一种实践 – 两张地图叠着用，效果翻倍。

如果你也被 Claude Code 的"探索税"折腾过，把这篇分享给同样在用 Claude Code 的朋友，让他们也少交点冤枉钱。

有什么问题或者你有更好的 token 优化方案？评论区聊聊。