GitNexus安装过程记录：Code Graph RAG 并联动 Claude Code

本地部署GitNexus结合Claude Code进行代码分析

GitNexus 本地 CLI + MCP + Claude Code 的完整部署流程，暂时不需要webui

GitNexus 的 CLI 会在本地索引代码仓库，生成 .gitnexus/ 知识图谱目录，并通过 MCP 给 Claude Code 提供 query、context、impact、detect_changes、rename、cypher 等代码分析工具。

官方说明 CLI 存储在本地，不上传代码；索引数据保存在仓库内 .gitnexus/，全局注册表保存在 ~/.gitnexus/registry.json

GitNexus与Claude Code关系示意图

1.1 检查基础环境

如果 node -v 低于 20，先升级 Node。推荐用 nvm 安装 Node 20

bash 复制代码

node -v
npm -v
npx -v
git --version
claude --version

本人环境

v24.14.1

11.11.0

git version 2.34.1

2.1.119 (Claude Code)

1.2 安装 nvm

GitNexus 可以不全局安装，直接用 npx gitnexus ...。官方推荐这种方式用于快速使用。

但你是长期要配合 Claude Code 使用，建议全局安装一次：

bash 复制代码

npm install -g gitnexus

报错

（1）当前 Node.js 是 v24.14.1，太新了，GitNexus 及其原生依赖更适合用 Node 20 LTS

（2）gitnexus 间接依赖 onnxruntime-node，安装时它需要下载 ONNX Runtime 的预编译文件

先把 Node.js 从 v24 切到 v20

安装 nvm，如果你已经有 nvm，可以跳过这一步

bash 复制代码

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

重新加载 shell

bash 复制代码

source ~/.bashrc

安装并切换到 Node 20

bash 复制代码

nvm install 20
nvm use 20
nvm alias default 20

报错，因为我之前安装claude code配置过 npm 全局安装目录：~/.npm-global

而 nvm 会为每个 Node 版本管理自己的全局 npm 目录，所以它和 .npmrc 里的 prefix 冲突。解决方式是删除 npm 的 prefix 配置，再切换 Node 20

1.3 修改npm prefix配置

查看当前 npm prefix 配置

bash 复制代码

cat ~/.npmrc
npm config get prefix
npm config list

删除 ~/.npm-global

bash 复制代码

# 删除 ~/.npmrc 中的 prefix 配置
sed -i '/^prefix=/d' ~/.npmrc

# 确认已经删干净
cat ~/.npmrc
npm config get prefix

1.4 切换到 nvm 的 Node 20

bash 复制代码

nvm use --delete-prefix v20.20.2

Now using node v20.20.2 (npm v10.8.2)

bash 复制代码

nvm alias default v20.20.2

default -> v20.20.2

检查路径

bash 复制代码

node -v
npm -v
which node
which npm

正确结果应类似

v20.20.2

10.8.2

/home/xxx/.nvm/versions/node/v20.20.2/bin/node

/home/xxx/.nvm/versions/node/v20.20.2/bin/npm

1.5 重新安装 Claude Code

重新安装 Claude Code 到 nvm 的 Node 20 环境

之前的 Claude Code 装在：/home/xxx/.npm-global/lib切到 nvm 后，这些全局包不会自动继承。所以建议重新装一遍 Claude Code：

bash 复制代码

npm install -g @anthropic-ai/claude-code

验证：

bash 复制代码

claude --version
which claude

正确路径应该类似

2.1.119 (Claude Code)

/home/xxx/.nvm/versions/node/v20.20.2/bin/claude

1.6 安装 GitNexus

先不要开 embeddings，所以继续跳过 onnxruntime-node 下载脚本：

bash 复制代码

export ONNXRUNTIME_NODE_INSTALL=skip
npm install -g gitnexus@1.6.3

验证：

bash 复制代码

gitnexus --version
which gitnexus

1.6.3

/home/xxx/.nvm/versions/node/v20.20.2/bin/gitnexus

1.7 索引本地代码仓库

进入项目目录

bash 复制代码

cd your-project/

（1）对当前 Git 仓库进行本地代码索引

只建立代码结构图谱，不生成语义向量索引

bash 复制代码

gitnexus analyze

它会扫描当前仓库中的代码文件，解析符号、函数、类、调用关系、模块关系等，构建 GitNexus 的本地知识图谱，并把索引结果保存到当前仓库下的：.gitnexus/
只建立代码结构图谱，不生成语义向量索引

它通常会解析：文件、函数、类、方法、变量、导入关系、调用关系、模块关系、代码流程、依赖关系

优点：安装和运行更稳、速度更快、占用内存更低、不容易触发 onnxruntime-node 问题、适合 Claude Code 做调用链、影响范围、变量关系、架构分析

缺点：、语义搜索能力较弱、更依赖关键词、符号名、函数名、文件路径

在代码结构图谱之外，再生成语义向量 embeddings

bash 复制代码

gitnexus analyze --embeddings

除了上面的结构化代码图谱外，它还会对代码片段、文档片段等生成向量表示，用于更强的语义检索。

优点：可以更好地支持自然语言搜索、即使你没有准确写出函数名，也可能找到相关代码、适合问"哪里实现了子图切分逻辑""哪个模块负责位姿继承"这类语义问题

缺点：安装依赖更复杂、更容易触发 onnxruntime-node 下载或运行问题、索引速度更慢、占用内存和磁盘更多、大仓库容易 OOM、对服务器网络和 Node 环境要求更高

推荐执行顺序

先跑：

bash 复制代码

gitnexus analyze
gitnexus status
gitnexus list

如果能正常在 Claude Code 里使用 GitNexus MCP，再决定是否升级为 embeddings：

bash 复制代码

gitnexus analyze --force --embeddings

（2）查看当前仓库的 GitNexus 索引状态

bash 复制代码

gitnexus status

它一般用于确认：

当前仓库是否已经被 GitNexus 索引

索引是否存在

索引是否过期

当前仓库路径是否被注册

索引中包含多少符号、关系、流程等信息

通俗说，它回答的是：

"我当前这个项目的 GitNexus 索引能不能用？"

如果你刚改了大量代码，可以先运行：

gitnexus status

如果显示索引过期，再重新执行：

gitnexus analyze

（3）列出本机所有已经被 GitNexus 索引过的仓库

bash 复制代码

gitnexus list

GitNexus 不只服务当前仓库，它会把已索引仓库登记到全局注册表：

~/.gitnexus/registry.json

所以 gitnexus list 会从这个全局注册表里读取信息，告诉你本机有哪些仓库已经建立过 GitNexus 索引。

通俗说，它回答的是：

"我这台电脑上 Claude Code 通过 GitNexus MCP 能看到哪些仓库？"

这对你后面同时分析多个项目很重要，gitnexus list 就能列出它们。之后 Claude Code 通过 GitNexus MCP 也可以在多个仓库之间做对比分析。

三条命令的关系可以理解为：

gitnexus analyze

= 给当前仓库建立本地知识图谱

gitnexus status

= 检查当前仓库的知识图谱是否正常

gitnexus list

= 查看本机所有已登记的 GitNexus 仓库

日常使用流程

bash 复制代码

cd your-project/

1.8 配置Claude Code MCP

（1）什么是MCP？

MCP 是 Model Context Protocol，中文可以理解为模型上下文协议。它是一个开放协议，用来把大语言模型应用，例如 Claude Code、Cursor、ChatGPT、AI IDE 等，与外部系统连接起来

通俗讲：

没有 MCP 时，Claude Code 就像一个很聪明的人，但它只能看到你当前给它的文字，不能稳定地访问外部工具。有 MCP 后，相当于给 Claude Code 接上了一组"专业外挂接口"：

Claude Code 本体

+GitNexus MCP

+GitHub MCP

+文件系统 MCP

+数据库 MCP

+搜索 MCP

+浏览器 MCP

它就不只是"聊天"，而是可以通过标准接口去查仓库、读文件、检索数据库、调用工具、分析影响范围。

MCP 就是 AI 工具的通用插口。

GitNexus 通过 MCP 把本地代码知识图谱交给 Claude Code，

Claude Code 就能更准确地查仓库、看调用链、分析影响范围、辅助改代码。

MCP 是统一插头。Claude Code 是电脑，GitNexus 是外设，MCP 是连接线和接口标准。

为什么不用 Claude Code 直接读仓库？

直接读仓库像人工翻书；GitNexus MCP 像先把书做成目录、索引和知识图谱，再让 Claude 查

（2）配置流程

第一阶段：Claude Code 官方 mcp add 跑通 GitNexus

确认 GitNexus 可用

bash 复制代码

gitnexus --version

确认仓库已索引

bash 复制代码

cd your-project/
gitnexus analyze
gitnexus status
gitnexus list

用 Claude Code 官方方式添加 MCP

bash 复制代码

claude mcp add gitnexus -- npx -y gitnexus mcp

显示 Added stdio MCP server gitnexus with command: npx -y gitnexus mcp to local config

File modified: /home/xxx/.claude.json [project: /home/xxx/your-project]

检查 Claude Code 是否识别

bash 复制代码

claude mcp list

显示 gitnexus: npx -y gitnexus mcp - ✓ Connected

现在就可以在项目目录中打开claude

bash 复制代码

claude

claude code中测试

bash 复制代码

请使用 GitNexus MCP，先读取 gitnexus://repos，确认 FVO-GS-SLAM 是否已经索引成功。

把现有 MCP 导入 cc-switch 管理。这样风险最低

第二阶段：cc-switch import 导入现有 MCP

第三阶段：以后用 cc-switch 统一管理 provider / MCP / skills

1.9 Ubuntu 22.04默认最高到GLIBCXX_3.4.30问题

系统：Ubuntu 22.04.5 LTS

GCC/G++：12.3.0

当前 libstdc++ 最高支持：GLIBCXX_3.4.30

GitNexus 需要：GLIBCXX_3.4.32

要支持 GLIBCXX_3.4.32，需要升级 libstdc++6

bash 复制代码

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt update
sudo apt install --only-upgrade libstdc++6

验证

bash 复制代码

strings /lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX_3.4.32
strings /lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX_3.4 | tail -20

如果能看到：GLIBCXX_3.4.32说明更新成功