Codegraphx (cgx)

CodeGraphX (CGX)

网站： techcraze00.github.io/CodeGraphX · npm： codegraphx

CodeGraphX (CGX) 是一款本地运行、节省 token 的代码库图引擎，面向 AI 编码 Agent 和开发者。它使用 Tree-sitter 解析源代码，在 SQLite 中存储双时态语义图，并通过 CLI 和 MCP 服务提供服务——因此，Agent 可以询问 “如果我修改这个函数，会导致什么问题？”，并在几百个 token 内得到准确答案，而不必阅读 50 个文件。

---

CodeGraphX 是什么？

定义—— CodeGraphX 是一个代码智能层：它以持久化、可查询的图结构呈现代码库中的符号（函数、类、变量）、它们之间的关系（calls、called_by、imports、inherits、跨语言的 API_CALLS），以及这些内容随时间的变化。

这是一种什么工具？ 它与语言服务器（LSP）或代码搜索索引属于同一类，但专为 大模型 Agent 打造：

• 语言服务器为编辑器逐个符号回答“跳转到定义”。
• grep / 嵌入搜索能查找文本，却无法识别结构。
• CodeGraphX回答结构化的全仓库推理问题——影响范围、依赖循环、跨语言契约、“这个符号到底是否存在？”——并以经过 token 优化的形式序列化答案，让 Agent 可以直接将其放入上下文中。

它要解决的核心问题—— AI 编码 Agent 会耗费大部分 token 预算来重新探索代码库：打开文件、滚动浏览、使用 grep 搜索，并在每次会话中反复阅读相同的模块。CodeGraphX 只需索引一次，就能通过图回答这些问题，让 Agent 把 token 用于推理，而不是扫描。

为什么它很有用（令牌经济学）

每个 Agent 操作都有令牌成本。来看一个常见问题：“如果我修改 validateInput，哪些内容会受到影响？”

方法	Agent 的操作	大致上下文成本
不使用 CGX	搜索 validateInput，打开约 15–50 个候选文件，并逐一阅读以追踪调用位置	数万个令牌，需要多次工具往返
使用 CGX	explain_impact({ symbol_name: "validateInput" }) → 返回一份小型 JSON，其中包含上游调用方和下游被调用方	几百个令牌，只需一次往返

CGX 会以 TOON（Token-Oriented Object Notation，面向令牌的对象表示法）而非 JSON 序列化图，从而进一步节省令牌。TOON 是一种紧凑的表格编码，可去除 JSON 令牌计数中占比很高的重复键和大括号。

**客观说明：**以下准确率数据是根据人工标注的语料库测得的。上面的令牌数据是对典型 Agent 行为的示意模型，并非实验室基准测试；具体比例取决于你的代码仓库和 Agent。真正带来优势的是其机制（一条有针对性的图查询，而非读取多个文件）。

CGX 最能发挥作用的场景：

• 大型或不熟悉的代码仓库，无法“通读所有内容”。
• 较长的 Agent 会话（图可作为缓存，Agent 无需重新构建）。
• 跨语言技术栈（React ⇄ Express/Flask/FastAPI），此类场景的调用图无法跨文件延伸。
• 重构和代码审查，此时影响范围分析以及死代码／损坏导入检测都很重要。

---

完整功能

功能	能提供什么
🧠 符号图	为每个函数／类／方法建立图，并包含 calls、called_by、imports、inherits 边
⚡ O(1) 符号查找	布隆过滤器无需访问数据库，即可返回 probable_yes／definite_no
💥 影响追踪	通过 SQL CTE 递归追踪上游（调用方）／下游（被调用方）的影响范围
🌉 跨语言链接	将前端 fetch／axios 调用与后端路由匹配，并建立带置信度评分的 API_CALLS 边
🕑 双时态历史记录	仅追加的图——可查询代码库在任意提交时的状态；任何内容都不会被删除
🩺 诊断检查	报告缺失／无法解析的导入、无法解析的调用目标、循环依赖和语法错误
✅ 任务验证	将任务描述与提交中实际修改的符号进行比对；标记未测试的新增内容
🔀 会话／分支差异	汇总与 HEAD 或某个分支相比新增／删除／修改的符号
🌐 交互式仪表板	在浏览器中查看整个代码库的 D3.js 力导向图
📦 TOON 产物	针对令牌优化的图和文件索引导出内容，可注入 Agent 上下文
🔐 100% 本地运行	无云服务、无遥测、无网络连接——代码绝不会离开本机
🤖 MCP 服务	向任何兼容 MCP 的 Agent 提供 6 个工具，并支持零配置自动索引

---

本项目使用的技术

层	技术
解析	使用 Tree-sitter 和各语言语法包（tree-sitter-python、-javascript、-typescript、-html、-css）
存储	通过 better-sqlite3 使用 SQLite（默认），或使用 Postgres（pg）；两者均通过 Kysely 类型安全的查询构建器访问
Agent 协议	通过标准输入／输出使用 Model Context Protocol SDK（@modelcontextprotocol/sdk）
概率查找	bloom-filters
令牌优化输出	TOON（@toon-format/toon）
命令行	Commander + @clack/prompts，用于交互式设置
文件监视	chokidar
运行时	Node.js ≥ 18，CommonJS

---

支持的语言

语言	扩展名	提取内容
Python	.py	函数、类、调用、导入（包括包相对导入 . / ..）、Flask/FastAPI 路由
JavaScript	.js、.jsx	函数、类、箭头函数、调用、导入/require、本地绑定、fetch/axios 调用、Express 路由
TypeScript	.ts、.tsx	与 JS 相同，另含 TypeScript 特有声明
HTML	.html	元素 / 结构符号
CSS	.css	选择器（类、ID）

---

安装

# Global (recommended)
npm install -g codegraphx

# Or per-project
npm install --save-dev codegraphx

# Verify
codegraphx --version        # 1.2.4

CLI 提供 codegraphx、cgx 和 MCP 入口点 cgx-mcp。

---

快速开始

cd your-project

# 1. Index the codebase → writes .codegraphx/ + .codegraphx.db
cgx init

# 2. Ask questions
cgx query authenticateUser                       # where is it, what calls it, what it calls
cgx impact authenticateUser --direction downstream --depth 5
cgx impact authenticateUser --direction upstream
cgx stats                                        # files / symbols / edges
cgx doctor                                       # health report

# 3. Optional live view
cgx watch                                        # re-index on file change
cgx dashboard                                    # open the D3 graph in a browser

重新扫描会完整重写。 每次运行 cgx init / cgx scan，都会从头重建 .codegraphx/：从磁盘删除的文件会从图中移除，过时的产物会被清除，数据库会对已移除的符号进行时间关闭处理，因此图始终与工作树保持一致。未更改的文件仍会从缓存提供，因此速度依然很快。

CLI 命令参考

命令	用途
cgx setup	将 MCP 服务和技能接入你的编码 CLI（见下文）
cgx init / cgx scan	为整个代码库建立索引
cgx query <symbol>	显示符号的文件、类型、calls 和 called_by
cgx impact <symbol> [--direction up/downstream] [--depth N]	追踪影响范围
cgx doctor [--json] [--strict] [--no-calls]	诊断：导入、调用、循环、语法
cgx stats	文件 / 符号 / 函数 / 类 / 边的数量
cgx watch	在文件更改时自动更新图
cgx dashboard	打开交互式 codegraph.html
cgx git-hook <install|remove>	在 post-commit / pre-push 时自动扫描
cgx session summary [--branch <b>]	当前会话的结构变更摘要
cgx verify --task <desc> --commit <hash>	验证任务与提交的证据

---

MCP 服务（适用于 AI Agent）

CodeGraphX 提供一个 MCP stdio 服务，开放 6 个工具。零配置： 无需预先扫描——服务首次在项目中启动时，会在后台为代码库建立索引。建立索引期间，get_graph_status 会报告 "indexing"；状态变为 "ready" 后，所有工具即可使用。

可用的 MCP 工具

工具	描述	参数
get_graph_status	就绪状态：indexing / ready / error，以及文件数量	—
list_files	列出已建立索引的文件	filter?: string
check_symbol_exists	O(1) Bloom 查询 → probable_yes / definite_no	name: string
explain_impact	符号的上游调用方和下游被调用方	symbol_name: string
verify_task	将任务描述与提交中的实际更改进行比较	task_description: string、commit_hash?: string
get_session_diff	当前会话 / 分支的结构摘要	branch?: string（默认值为 HEAD）

Agent 工作流示例

User: "What breaks if I change the validateInput function?"

Agent (via MCP):
  1. check_symbol_exists({ name: "validateInput" })   → { exists: "probable_yes" }
  2. explain_impact({ symbol_name: "validateInput" })
       → { used_by_upstream: ["src/auth.js::login"],
           breaks_downstream: ["src/api.js::handleRequest"] }

Result: exact answer, no file scanning.

选择项目根目录

服务会为其启动所在的目录建立索引。如果客户端未设置目录，请显式传入：

cgx-mcp --project-root /path/to/project
# or
CGX_PROJECT_ROOT=/path/to/project cgx-mcp

---

设置——有多简单？

一条命令

cgx setup

它会自动检测已安装的编码 CLI，让你多选要配置的 CLI，并逐一完成接入——无需手动编辑配置，也无需查找绝对路径。它会使用绝对 Node 路径 + 捆绑的 cgx-mcp 注册 MCP 服务（有原生命令时使用各 CLI 自带的命令，否则回退到 JSON 文件），因此全局安装和本地安装均可使用；此外还会按各 CLI 的格式安装 CGX 使用技能 / 说明。

cgx setup                                   # interactive multi-select
cgx setup --agents claude,gemini --yes      # non-interactive (CI / scripted)
cgx setup --project                         # register for the current repo only

默认采用用户级 / 全局注册，因此运行一次后即可在每个项目中使用——cgx-mcp 会根据 CLI 的启动位置解析项目。现有配置会予以保留；首次编辑前会先写入备份。

支持的编码 Agent CLI

Agent	检测方式	MCP 注册	技能 / 指令
Claude Code	PATH 中存在 claude 或存在 ~/.claude	claude mcp add → ~/.claude.json 或 .mcp.json	~/.claude/skills/cgx/SKILL.md
Gemini CLI	PATH 中存在 gemini	~/.gemini/settings.json 或 .gemini/settings.json	GEMINI.md（上下文文件）
Antigravity CLI	PATH 中存在 agy	~/.gemini/config/mcp_config.json 或 .agents/mcp_config.json	~/.gemini/skills/cgx/SKILL.md 或 .agents/skills/cgx/SKILL.md
OpenCode	PATH 中存在 opencode	opencode mcp → 配置文件	AGENTS.md
Cursor	存在 ~/.cursor	~/.cursor/mcp.json 或 .cursor/mcp.json	.cursor/rules/*.mdc

然后在任意项目中打开 CLI，并说 "use cgx to explore this codebase."

如果 cgx setup 无法正常工作 — 手动设置

MCP 条目的格式始终相同：使用 node 的绝对路径运行捆绑的 cgx-mcp（某些客户端无法继承你的 shell PATH）。使用以下命令查找：

which node                    # e.g. /usr/local/bin/node
which cgx-mcp                 # e.g. /usr/local/lib/node_modules/codegraphx/bin/cgx-mcp

Claude Code — 在项目中运行：

claude mcp add codegraphx -- npx -y -p codegraphx cgx-mcp

或使用 .mcp.json：

{ "mcpServers": { "codegraphx": { "command": "npx", "args": ["-y", "-p", "codegraphx", "cgx-mcp"] } } }

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。由于没有项目目录，请设置根目录：

{ "mcpServers": { "codegraphx": {
  "command": "npx",
  "args": ["-y", "-p", "codegraphx", "cgx-mcp", "--project-root", "/path/to/project"]
} } }

Gemini CLI — .gemini/settings.json（使用 node 的绝对路径）：

{ "mcpServers": { "codegraphx": {
  "command": "/ABSOLUTE/PATH/TO/node",
  "args": ["/ABSOLUTE/PATH/TO/node_modules/codegraphx/bin/cgx-mcp"],
  "cwd": "/ABSOLUTE/PATH/TO/PROJECT"
} } }

Antigravity CLI（agy）— 仅支持文件配置，不支持原生命令。全局配置文件 ~/.gemini/config/mcp_config.json 或项目配置文件 .agents/mcp_config.json：

{ "mcpServers": { "codegraphx": {
  "command": "/ABSOLUTE/PATH/TO/node",
  "args": ["/ABSOLUTE/PATH/TO/node_modules/codegraphx/bin/cgx-mcp"]
} } }

Cursor / Windsurf / 其他 MCP 客户端 — ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json），结构相同；将 cwd 指向项目根目录。

验证连接：

# inside the CLI
/mcp list           # should show: codegraphx — Connected (6 tools)

# or drive the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx -y -p codegraphx cgx-mcp

仍未连接？

1. 使用 node 的绝对路径，不要使用 npx。
2. 确保 cwd / --project-root 与你的项目完全一致。
3. 如果使用项目范围的 Gemini 设置，请运行 gemini trust。
4. 检查 stderr：node /path/to/cgx-mcp 2>&1 | head -20。

---

架构

数据流

Source files
   → parser.js            Tree-sitter, one adapter per language
   → entities.js          SymbolEntity / FileEntity / EdgeEntity (the domain model)
   → edgebuilder.js       CALLS / IMPORTS / INHERITS edges
   → cross-language-linker.js   fetch/axios ⇄ Express/Flask/FastAPI  →  API_CALLS edges
   → scanner.js           orchestrates a full scan; writes DB + .codegraphx/ artifacts
   → store/sql-store.js   Kysely ORM — append-only bi-temporal graph (SQLite / Postgres)

扫描完成后，项目根目录中的 .codegraphx.db 是事实来源。.codegraphx/ 目录存放派生工件：codegraph.html（仪表板）、codegraph-graph.json（D3）、codegraph.toon + file_index.toon（令牌优化版）、symbols.bloom 和 cache.json。

双时态、仅追加存储

files、symbols 和 edges 中的行永不删除。每行都包含 valid_from_commit_id 和 valid_to_commit_id；后者为 NULL 表示“当前有效”。编辑符号时，会关闭旧行并插入新行；删除文件时，会对其行进行时态关闭。这样，CGX 就能回答 “在提交 X 时，图是什么样的？”，并支持会话 / 分支差异和任务验证，同时永不丢失历史记录。

核心模块

模块	作用
src/parser.js	将文件路由到对应语言适配器；返回 declaredSymbols、imports、calls
src/languages/*	各语言的 Tree-sitter 适配器（python、javascript、typescript、html、css）
src/entities.js	SymbolEntity、FileEntity、EdgeEntity、Snapshot 领域模型
src/edgebuilder.js	根据解析出的引用构建结构边
src/cross-language-linker.js	在前端/后端边界之间创建带置信度评分的 API_CALLS 边
src/resolver.js	规范导入解析器（JS .//../、Python 包相对导入、点分路径）
src/scanner.js	runScan() — 索引入口；采用全量重写语义；mcpMode 会跳过开销较大的输出
src/store/sql-store.js	SqlGraphStore — 处理所有数据库读写；traceImpact 使用递归 SQL CTE；pruneDeletedFiles
src/store.js	GraphStore — 扫描器和 doctor 使用的内存 + cache.json 层
src/doctor.js	诊断引擎（导入 / 调用 / 循环 / 语法）
src/verifier.js	任务与提交的验证证据
src/sdk/index.js	IntelligenceSDK — 用于嵌入 CGX 的编程 API
src/server/mcp-server.js	CodeGraphXServer — MCP stdio 服务
src/setup/*	cgx setup 编排器 + 各 CLI 适配器
src/db/*	Kysely db 实例 + 迁移（设置 DB_DIALECT=postgres + DATABASE_URL 即可切换）

---

基准测试与准确度

CGX 的目标是让人们可以信赖图谱而不必阅读代码，因此会使用人工标注的黄金语料库（tests/golden/）评估图谱；其中每个符号、边、跨语言链接和导入循环都已知。相同的测试框架也用于 CI 门禁（tests/golden/accuracy.test.js）——解析器回归会导致构建失败。

提取准确度（精选语料库：3 个夹具、9 个文件、20 个符号）：

类别	精确率	召回率	F1
符号	100%	100%	100%
结构边（CALLS / IMPORTS / INHERITS）	100%	100%	100%
跨语言 API 链接	100%	100%	100%
端点标记	100%	100%	100%

推理与确定性：

检查项	结果
影响追踪（精确可达集合）	4/4 (100%)
循环导入检测（召回率）	1/1 (100%)
循环导入误报	0
多次重新扫描结果一致	是

**吞吐量：**在该语料库上约为 82 个文件/秒、183 个符号/秒（完整扫描约 110 ms）。

复现并重新生成 BENCHMARK.md + benchmark-results.json：

npm run benchmark

这些数据验证的是受控语料库上的提取正确性，并不代表覆盖了每一种语言结构。若要扩展测试范围，可在 tests/golden/<name>/ 下添加夹具，并附上 ground-truth.json。

---

跨语言智能分析

扫描期间，CGX 会提取客户端发出的 HTTP 请求和服务端公开的路由，然后将它们匹配为带置信度评分的 API_CALLS 边：

fetch('/api/users')        ──API_CALLS(0.9)──▶  app.get('/api/users', listUsers)   [Express]
axios.post('/api/orders')  ──API_CALLS(0.9)──▶  @router.post('/api/orders')        [FastAPI]
fetch(`/api/users/${id}`)  ──API_CALLS(0.7)──▶  @app.route('/api/users/<id>')      [Flask]

• 前端：fetch(...)（含 method）、axios.get/post/...、axios({ url, method })。
• **后端：**Express/router、Flask（@app.route(..., methods=[...])）、FastAPI（@router.get、@app.post、…）。
• **置信度：**路径和方法完全匹配时为 0.9，路径完全匹配/方法不同时为 0.75，参数化路径和方法匹配时为 0.7，参数化路径/方法不同时为 0.55。路径参数（:id、{id}、<int:id>）会先进行规范化，因此 /api/users/${id} 会链接到 /api/users/{user_id}。

路由处理函数会添加 endpoint 本体标记，而 explain_impact 会遍历 API_CALLS 边——因此，*“哪些代码会调用这个后端处理函数？”*会返回跨语言边界的前端调用方。

---

安全与隐私

• ✅ 100% 本地运行 — 无网络连接、无遥测、无云同步。
• ✅ 只读 — CGX 从不修改你的源代码。
• ✅ 仅静态分析 — 代码只会被解析，绝不会执行。
• ✅ 可配置忽略项 — 通过 .codegraphxrc 排除敏感路径。

MCP 服务以你终端的权限运行，只读取符合已配置扩展名和忽略规则的文件。对于敏感项目，请在沙箱或容器中运行。

---

配置

项目配置存放在 .codegraphxrc（JSON）或 codegraphx.config.json 中：

{
  "extensions": [".py", ".js", ".ts", ".jsx", ".tsx", ".html", ".css"],
  "ignore": [".git", "node_modules", "__pycache__", ".venv", "dist", "build", "coverage"],
  "outputDir": ".codegraphx",
  "outputFile": "codebase.json",
  "bloomErrorRate": 0.01
}

将 .codegraphx/ 和 .codegraphx.db 添加到 .gitignore 中——它们是构建产物。

---

常见问题

每次都需要运行扫描吗？ 不需要——MCP 服务会在首次使用时自动建立索引。更改后重新扫描（或运行 cgx watch）即可刷新。每次重新扫描都会进行一次干净的完整重写，因此删除和重命名不会留下过时的图数据。

大型代码库呢？ 没问题——增量解析意味着未更改的文件会从缓存中读取；只有更改过的文件才会重新解析。

私有或专有代码呢？ 没问题——所有操作都在本地运行，不会有任何内容离开你的设备。

MCP 显示“Disconnected”？ 使用 node 的绝对路径，确认 cwd/--project-root，为项目范围运行 gemini trust，并检查标准错误输出（参见上文的手动设置）。

Bloom filter 的准确度如何？ 可通过 bloomErrorRate 调整（默认值为 0.01）。误报只会触发回退查询——不会出现漏报。

---

参与贡献

git clone https://github.com/techcraze00/CodeGraphX.git
cd codegraphx
npm install
npm link          # exposes `codegraphx` / `cgx` globally
npm test

添加一种语言：将 Tree-sitter 语法添加到 package.json，在 src/languages/<lang>/ 下创建适配器，在 src/languages/index.js 中注册，并在 tests/golden/ 下添加一个黄金测试样例。

---

许可证

MIT © 2026 Prayas Jadhav。请参阅 LICENSE。

---

链接

• 网站 / 文档： techcraze00.github.io/CodeGraphX
• 软件包： npm 上的 codegraphx
• 代码仓库： github.com/techcraze00/CodeGraphX
• 问题反馈： github.com/techcraze00/CodeGraphX/issues

致谢

Tree-sitter · Model Context Protocol · Kysely · TOON · bloom-filters

CodeGraphX — 即刻了解你的代码库。

_{为开发者和 AI Agent 而打造。}