GitNexus
把代码库索引成知识图谱的代码智能引擎,通过 17 个 MCP 工具和 agent skills 给 Cursor、Claude Code、Codex 等编码 agent 提供依赖关系、调用链、影响面分析等结构化上下文,另有纯浏览器运行的 Web UI 支持 Graph RAG 对话。核心亮点是在索引阶段预计算聚类、调用链、置信度,一次工具调用就能拿到完整上下文,比传统 Graph RAG 多轮查询更省 token 且小模型也能用;支持 14 种语言、多仓库、Docker 部署,本地优先保护隐私。注意:PolyForm Noncommercial 非商业许可,商用需另谈授权。
README
GitNexus (Akon Labs)
⚠️ 重要提示: GitNexus 没有任何官方加密货币、代币或币。任何在 Pump.fun 或其他平台上使用 GitNexus 名称的代币/币与本项目及其维护者无关,且未获其认可或创建。请勿购买任何声称与 GitNexus 有关联的加密货币。
智能体上下文的神经系统。
将任意代码库索引为知识图谱 —— 每个依赖、调用链、聚类和执行流 —— 然后通过智能 MCP 工具将其暴露出来,让 AI 智能体永不遗漏代码。
💬 Discord · 🌐 Web UI · 🏢 企业版(SaaS 与自托管)
https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
像 DeepWiki,但更深。 DeepWiki 帮助你_理解_代码。GitNexus 让你能_分析_它 —— 知识图谱追踪每一个关系,而不仅仅是描述。
TL;DR: CLI + MCP 让你的 AI 智能体变得可靠 —— 它为 Cursor、Claude Code、Antigravity、Codex 等工具提供深度的代码库架构视图,使它们不再遗漏依赖、破坏调用链、或盲目地提交编辑。即使是较小的模型也能获得完整的架构清晰度。Web UI 是在浏览器中与任意仓库快速对话的方式。
快速开始
# 1. 索引你的仓库(在仓库根目录运行)
npx gitnexus analyze
# 2. 连接你的编辑器(一次性,自动检测 Claude Code、Cursor、Codex …)
npx gitnexus setup
就这样。analyze 索引代码库、安装 agent skills、注册 Claude Code hooks,并创建 AGENTS.md / CLAUDE.md 上下文文件 —— 全部一条命令完成。setup 写入 MCP 配置,让你的 AI 智能体能够使用该知识图谱。
在 npm 11.x 上?
npx在安装过程中可能崩溃,报错Cannot destructure property 'package' of 'node.target'(这是 npm/arborist 的 bug,发生在 GitNexus 运行之前)。请改用 pnpm —— 它会显式构建原生依赖:pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze或者全局安装(
npm install -g gitnexus@latest)后运行gitnexus analyze。参见 #1939。
最快的 MCP 启动方式: 在运行
gitnexus setup之前全局安装(npm i -g gitnexus)—— 这会写入绝对路径的 MCP 配置,完全绕过npx。在冷缓存情况下,基于npx的 MCP 安装可能超过 Claude Code 的MCP_TIMEOUT默认值(约 30 秒)。
没有 C++ 工具链? 在
npm install -g gitnexus之前设置GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1,跳过tree-sitter-dart、tree-sitter-proto、tree-sitter-swift和tree-sitter-kotlin的内置 grammar 物化/构建 —— 这四种语言将不会被解析,但安装可在几秒内完成,无需python3/make/g++。严格为=1才生效 —— 任何其他值都会回退到重建。
在 HTTP 代理 / 区域防火墙后面?
onnxruntime-node的 postinstall 会从api.nuget.org下载可选的 CUDA 二进制文件,且忽略HTTP_PROXY/HTTPS_PROXY(#2370)。embedding 技术栈是可选依赖,因此下载失败不再导致安装中断 —— 而且它能自愈:第一次运行gitnexus analyze --embeddings(或gitnexus embeddings install)时,会通过你的 npm registry 配置(镜像/代理生效,不走 NuGet)将技术栈拉取到~/.gitnexus/embedding-runtime(可用GITNEXUS_EMBEDDING_RUNTIME_DIR覆盖)。按需前缀需要支持module.registerHooks的 Node 版本(22.x 上 ≥ 22.15,23.x 上 ≥ 23.5);在旧版 Node 上,将技术栈保留在安装本身中:ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus(在所有受支持的 Node 上均有效)。
关于
tree-sitter-kotlin: 与 Dart/Proto/Swift 一样,Kotlin 是一种内置(vendored) grammar(位于gitnexus/vendor/tree-sitter-kotlin)。上游只提供源码(没有预编译二进制),因此 GitNexus 自己交叉构建平台预编译(通过build-tree-sitter-prebuildsGitHub Actions 工作流)并将其内置 —— 这与 Dart、Proto 和 Swift 使用相同的统一管道。node-gyp-build在 require 时选择正确的.node文件,所以不需要 C/C++ 工具链。如果没有匹配你平台架构的预编译,只有 Kotlin(.kt/.kts)解析不可用;gitnexus的其他功能不受影响。
部署到 Render
一键部署 GitNexus:
该 Blueprint 会创建两个服务。gitnexus-server 以私有服务方式运行 gitnexus serve:没有公共 URL,只能通过 Render 的私有网络访问,并配有持久化磁盘用于存储索引和克隆的仓库。gitnexus-web 是公共服务,它提供 UI 并将 /api/* 反向代理到 server,因此浏览器只需与单一来源通信。
按 Blueprint 的默认配置,这大约每月 $35:server 的 standard 实例 $25,web 服务的 starter 实例 $7,10 GB 磁盘 $2.50。其他方案参见 Render 的定价。
部署会生成一个访问令牌,UI 在首次使用时要求输入:
- 在你的 Render dashboard 中打开
gitnexus-web服务。 - 从环境 标签页复制
GITNEXUS_SERVE_AUTH_TOKEN。 - 加载站点并将令牌粘贴到提示框中(或设置面板)。
每个 /api/* 请求都会将该令牌作为 header 携带,没有令牌时代理返回 401。浏览器将其保存在 sessionStorage 中,因此新标签页会再次要求输入。要轮换令牌,编辑环境变量并重新部署。
代理在转发前会剥离 Origin,因此服务器的 CSRF 防护对代理流量不起作用;它按设计放行无 Origin 的请求。令牌是该部署上唯一的控制手段,不是防护层之后的第二层。任何持有令牌的人都可以读取所有已索引的仓库。参见 SECURITY.md。
索引受内存限制。如果 gitnexus-server 在大型仓库上内存不足,请升级其 plan,该配置决定了可用 RAM:standard 为 2 GB,pro 为 4 GB。仅当磁盘被克隆和索引占满时才需要提高 sizeGB。
使用 GitNexus 的两种方式
| CLI + MCP(推荐) | Web UI | |
|---|---|---|
| 是什么 | 本地索引仓库,通过 MCP 连接 AI 智能体 | 浏览器中的可视化图谱浏览器 + AI 聊天 |
| 适用 | 使用 Cursor、Claude Code、Antigravity、Codex、Windsurf、OpenCode 的日常开发 | 快速探索、演示、一次性分析 |
| 规模 | 完整仓库,任意大小 | 受浏览器内存限制(约 5k 文件),或通过后端模式无限 |
| 安装 | npm install -g gitnexus |
无需安装 —— gitnexus.vercel.app |
| 存储 | LadybugDB 原生(快速、持久) | LadybugDB WASM(内存中、每会话) |
| 解析 | Tree-sitter 原生绑定 | Tree-sitter WASM |
| 隐私 | 一切本地化,无网络 | 一切在浏览器内,无服务器 |
桥接模式:
gitnexus serve将两者连接起来 —— Web UI 自动检测本地服务器,可以浏览你所有通过 CLI 索引的仓库,无需重新上传或重新索引。
为什么需要知识图谱?
像 Cursor、Claude Code、Codex、Cline、Roo Code 和 Windsurf 这样的工具很强大 —— 但它们并不真正了解你的代码库结构。于是会发生这种情况:
- AI 修改了
UserService.validate() - 不知道有 47 个函数依赖其返回类型
- 破坏性变更上线了
传统的 Graph RAG 将原始图边交给 LLM,寄希望于它探索得足够充分。GitNexus 在索引时预计算结构 —— 聚类、追踪、评分 —— 使工具一次调用即可返回完整上下文:
flowchart TB
subgraph Traditional["Traditional Graph RAG"]
direction TB
U1["User: What depends on UserService?"]
U1 --> LLM1["LLM receives raw graph"]
LLM1 --> Q1["Query 1: Find callers"]
Q1 --> Q2["Query 2: What files?"]
Q2 --> Q3["Query 3: Filter tests?"]
Q3 --> Q4["Query 4: High-risk?"]
Q4 --> OUT1["Answer after 4+ queries"]
end
subgraph GN["GitNexus Smart Tools"]
direction TB
U2["User: What depends on UserService?"]
U2 --> TOOL["impact UserService upstream"]
TOOL --> PRECOMP["Pre-structured response:
8 callers, 3 clusters, all 90%+ confidence"]
PRECOMP --> OUT2["Complete answer, 1 query"]
end
核心创新:预计算的关系智能
- 可靠性 —— LLM 不可能遗漏上下文;它已经在工具响应中
- Token 效率 —— 不需要 10 次查询链来理解一个函数
- 模型民主化 —— 较小的 LLM 也能工作,因为工具承担了繁重的工作
你的 AI 智能体能获得什么
17 个 MCP 工具(15 个每仓库 + 2 个组级)
| 工具 | 功能 |
|---|---|
list_repos |
发现所有已索引的仓库(分页 —— limit/offset) |
query |
按进程分组的混合搜索(BM25 + 语义 + RRF) |
context |
360 度符号视图 —— 分类引用、进程参与 |
impact |
爆炸半径分析,带深度分组和置信度 |
trace |
两个符号之间的最短有向路径(调用 + 类成员边) |
detect_changes |
Git 差异影响 —— 将变更行映射到受影响的进程 |
check |
针对已索引图谱的只读结构检查 |
rename |
基于图谱 + 文本搜索的多文件协调重命名 |
cypher |
原始 Cypher 图谱查询 |
route_map |
API 路由图 —— 哪些组件请求哪些端点,以及对应的 handler |
tool_map |
MCP/RPC 工具定义 —— 它们的定义位置和处理位置 |
shape_check |
根据消费者的属性访问验证 API 响应形状 |
api_impact |
API 路由 handler 的变更前影响报告 |
explain |
解释持久化的污点分析发现(source→sink 流,--pdg 索引) |
pdg_query |
语句级控制/数据依赖查询(--pdg 索引) |
group_list |
列出配置的仓库组 |
group_sync |
重建组的合约注册表(Contract Registry)和跨仓库链接 |
每仓库工具接受可选的
repo参数(仅索引了一个仓库时可省略)以及可选的branch参数(用于使用gitnexus analyze --branch固定的索引)。省略branch时查询工作区索引,该索引跟随你检出的工作树 —— 切换分支并重新运行gitnexus analyze会增量更新它。explain和pdg_query需要使用gitnexus analyze --pdg构建的索引。
即时上下文的资源
| 资源 | 用途 |
|---|---|
gitnexus://repos |
列出所有已索引的仓库(先读这个) |
gitnexus://setup |
为智能体提供的设置和使用指南 |
gitnexus://repo/{name}/context |
代码库统计、过期检查和可用工具 |
gitnexus://repo/{name}/clusters |
所有功能聚类及内聚度分数 |
gitnexus://repo/{name}/cluster/{name} |
聚类成员和详细信息 |
gitnexus://repo/{name}/processes |
所有执行流 |
gitnexus://repo/{name}/process/{name} |
带步骤的完整进程追踪 |
gitnexus://repo/{name}/schema |
用于 Cypher 查询的图谱模式 |
gitnexus://group/{name}/contracts |
组的提取合约和交叉链接 |
gitnexus://group/{name}/status |
组中仓库的过期状态 |
2 个引导式工作流的 MCP 提示词
| 提示词 | 功能 |
|---|---|
detect_impact |
提交前变更分析 —— 范围、受影响的进程、风险等级 |
generate_map |
从知识图谱生成带 mermaid 图的架构文档 |
自动安装到 .claude/skills/ 和 .agents/skills/(如果存在 .agents/)的智能体技能
- Exploring(探索) — 使用知识图谱导航不熟悉的代码
- Debugging(调试) — 通过调用链追踪 bug
- Impact Analysis(影响分析) — 在修改前分析爆炸半径
- Refactoring(重构) — 使用依赖映射规划安全重构
- Guide(指南) — 针对智能体的 GitNexus 工具/资源/模式参考
- CLI — 按请求运行 analyze/status/clean/wiki 命令
- PDG Query(PDG 查询) — 语句级控制/数据依赖查询(
--pdg索引) - Taint Analysis(污点分析) — source→sink 数据流发现(
--pdg索引) - Plan(
/gitnexus-plan) — 由图谱和 PDG 切片支撑的可实施工程计划 - Work(
/gitnexus-work) — 以影响检查的、detect_changes门控的原子提交来执行计划 - Review(
/gitnexus-review) — 对 PR、分支、范围或本地差异进行图谱支撑的审查,包含污点扫描和按领域的专家视角 - LFG(
/gitnexus-lfg) — 完整流水线:plan → 用户门控 → work → review
仓库特定技能 — 运行 gitnexus analyze --skills,GitNexus 会检测你代码库的功能区域(通过 Leiden 社区检测),并将每个区域生成为 .claude/skills/gitnexus-area-<name>/ 下的直接项目技能。每个技能描述一个模块的关键文件、入口点、执行流和跨区域连接,并在每次 --skills 运行时重新生成以保持最新。
当仓库包含 .agents/ 目录时,标准技能和生成的技能也会镜像到 .agents/skills/(例如 .agents/skills/gitnexus-cli/、.agents/skills/gitnexus-area-<name>/),使读取仓库本地 .agents/skills/ 的智能体(如 Codex)保持同步。
编辑器设置
gitnexus setup 自动检测你的编辑器并写入正确的全局 MCP 配置。运行一次即可。要仅配置选定的集成,传入 --coding-agent/-c 加逗号分隔的列表,例如 gitnexus setup -c cursor,codex。
| 编辑器 | MCP | Skills | Hooks(自动增强) | 支持 |
|---|---|---|---|---|
| Claude Code | 是 | 是 | 是(PreToolUse + PostToolUse) | 完整 |
| Cursor | 是 | 是 | 是(postToolUse,手动安装) | 完整 |
| Antigravity(Google) | 是 | 是 | 是(AfterTool,Gemini CLI hooks schema)¹ | 完整 |
| Codex | 是 | 是 | 是(PreToolUse + PostToolUse,Codex hooks) | 完整 |
| OpenCode | 是 | 是 | — | MCP + Skills |
| CodeBuddy(腾讯) | 是 | 是 | — | MCP + Skills |
| Qoder(阿里巴巴) | 是 | 是 | — | MCP + Skills |
| Windsurf | 是 | — | — | MCP |
Claude Code 和 Codex 获得最深度的集成:MCP 工具 + agent skills + PreToolUse hooks(用图谱上下文丰富搜索)+ PostToolUse hooks(在提交后检测索引过期并提示智能体重新索引)。
手动 MCP 配置(如果你不想运行¹ Antigravity hooks 遵循 Gemini CLI hooks 参考文档(Antigravity 2.0 是 Gemini CLI 的文档化后续产品)。增强在
AfterTool中运行,因为在 Gemini 协议中BeforeTool没有上下文注入通道 —— 智能体通过hookSpecificOutput.additionalContext看到附加到工具结果上的图谱上下文。索引过期提示在git commit/merge/rebase/cherry-pick/pull成功后通过同一通道送达。如果 Antigravity 特定的 hooks 文档与 Gemini CLI 的有所差异,schema 可能演变;实现将追踪这些变化。
gitnexus setup)Claude Code(完整支持 —— MCP + skills + hooks):
# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp
# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp
Codex(完整支持 —— MCP + skills + hooks):
codex mcp add gitnexus -- npx -y gitnexus@latest mcp
或者通过 ~/.codex/config.toml(系统范围)/ .codex/config.toml(项目范围):
[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]
Codex hooks(PreToolUse 图谱增强 + PostToolUse 索引过期检测,位于 ~/.codex/hooks.json,与 Claude Code 相同的 schema)需要捆绑的适配器脚本,因此它们由 gitnexus setup -c codex 安装,而非手动安装。
或者,将一切安装为 Codex 插件(MCP + skills + hooks 一步到位):
codex plugin marketplace add abhigyanpatwari/GitNexus
# 然后在 Codex 中:/plugins → 安装 "GitNexus"
Codex 说明: SessionStart 刻意未注册 —— Codex 原生读取 AGENTS.md,其中已经携带 GitNexus 上下文块。新安装的 hooks 需要在 Codex 中通过
/hooks进行一次性审批后才能运行。选择一种安装方式(gitnexus setup -c codex或插件):插件 hooks 与~/.codex/hooks.json并行加载,因此同时安装两者可能会在每次工具调用时触发重复 hooks。
Cursor(~/.cursor/mcp.json —— 全局,适用于所有项目):
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
Antigravity(Google)— ~/.gemini/antigravity/mcp_config.json:
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
gitnexus setup还会将一个AfterTool条目合并到~/.gemini/settings.json(使用规范的 Gemini CLI hooks schema),并将 skills 安装到~/.gemini/antigravity/skills/。现有的用户 hooks 会被保留。hook 适配器的路径在安装时会被重写,因此请运行gitnexus setup而非手动编辑。
OpenCode(~/.config/opencode/config.json):
{
"mcp": {
"gitnexus": {
"type": "local",
"command": ["gitnexus", "mcp"]
}
}
}
CodeBuddy(腾讯)— 优先级链,编辑第一个存在的非空文件:~/.codebuddy/.mcp.json(推荐)→ ~/.codebuddy/mcp.json(已弃用)→ ~/.codebuddy.json(旧版)。CodeBuddy 只读取第一个存在的文件,因此向比当前使用文件更高优先级的文件添加服务器会隐藏其下方的服务器。仅在都不存在时创建 ~/.codebuddy/.mcp.json:
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
Qoder(阿里巴巴)— ~/.qoder.json:
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
MCP 只读模式在启动 MCP 服务器前设置 GITNEXUS_MCP_READ_ONLY=1,只暴露经过验证的单仓库读取接口。原始 cypher、重命名和组工具、组路由以及组资源将从发现中排除,并在后端分发前被拒绝。工具描述和生成的 setup/context 资源会被清理,使其不推荐不可用的路由。
当变量未设置或为 0 时,默认行为不变。任何其他值都会导致服务器启动失败,而不是静默削弱策略。
将 GITNEXUS_MCP_ALLOWED_REPOS 设置为规范注册表名称或绝对索引路径的逗号分隔列表。条目在启动时会被修剪、对照注册表解析并去重。当恰好允许一个仓库时,它成为隐式默认值;当允许多个仓库时,调用者必须选择一个,除非同时设置了 GITNEXUS_MCP_DEFAULT_REPO。
默认仓库必须解析为允许的仓库。无效、歧义、空白或不匹配的配置会在 stdio 或 HTTP 开始服务之前使启动失败。允许列表适用于工具、别名、发现、资源、模板、隐式解析和嵌入式 HTTP;隐藏的仓库细节不包含在选择错误中。仅设置 GITNEXUS_MCP_DEFAULT_REPO 是选择默认值而不限制显式的仓库选择。注册表中名称重复的允许仓库必须通过路径配置,其 context 资源仅以唯一名称形式提供服务。
query、context 和 impact 工具接受一个可选的正整数 maxTokens 参数。它使用确定的每 token 四个 UTF-8 字节的估算来限制完整格式化的 MCP 响应(包括提示和错误文本)。当需要截断时,响应以 … 结尾并保持有效的 UTF-8。
设置 GITNEXUS_MCP_DEFAULT_MAX_TOKENS 可在调用者不发送 maxTokens 时应用相同的保护。显式的工具参数优先。两者都未设置时保留现有响应的逐字节输出;这是一个传输保护措施,不是语义分页或精确的模型特定 tokenizer 限制。
CLI 参考
日常命令:
gitnexus setup # 为检测到的编辑器配置 MCP(一次性;-c 选择)
gitnexus analyze [path] # 索引仓库(或更新过期索引)
gitnexus mcp # 启动 MCP 服务器(stdio)—— 服务所有已索引的仓库
gitnexus serve # 为 Web UI 连接启动本地 HTTP 服务器(多仓库)
gitnexus eval-server # 启动轻量级评估 HTTP 工具(默认仅回环)
gitnexus list # 列出所有已索引的仓库
gitnexus status # 显示当前仓库的索引状态
gitnexus clean # 删除当前仓库的索引
gitnexus wiki [path] # 从知识图谱生成仓库 wiki
gitnexus uninstall # 预览移除 GitNexus MCP/skills/hooks(--force 执行)
你也可以直接从终端查询图谱 —— gitnexus query、context、impact、trace、cypher、detect-changes 和 check 对应同名 MCP 工具,gitnexus doctor 打印运行时平台能力。
eval-server 绑定gitnexus eval-server 默认绑定到 127.0.0.1。回环绑定不需要认证。任何非回环绑定,包括 0.0.0.0、局域网地址或解析为局域网 IPv4 地址的主机名,都需要 GITNEXUS_AUTH_TOKEN。之后每个端点都要求精确的 Authorization: Bearer <token> 头。
GITNEXUS_AUTH_TOKEN='replace-me' gitnexus eval-server --host 0.0.0.0
令牌可以设置在 shell、工作目录中的 .env.local 或 .env 中。优先级为 shell > .env.local > .env。只从这些文件中读取 GITNEXUS_AUTH_TOKEN;其他值不会添加到进程环境中。请保持令牌文件不提交。
analyze 标志gitnexus analyze --force # 完全重建:重新解析 + 图谱重建 + FTS 重建
gitnexus analyze --repair-fts # 快速路径:仅重建/验证现有索引数据上的 FTS 索引
gitnexus analyze --skills # 从检测到的社区生成仓库特定技能文件
gitnexus analyze --skip-embeddings # 跳过 embedding 生成(更快)
gitnexus analyze --embeddings [limit] # 启用 embedding 生成(更慢,搜索更好)
gitnexus analyze --skip-agents-md # 保留自定义 AGENTS.md/CLAUDE.md gitnexus 区块的编辑
gitnexus analyze --skip-skills # 跳过在 .claude/skills/ 和 .agents/skills/ 下安装标准技能文件
gitnexus analyze --skip-git # 索引不是 Git 仓库的文件夹
gitnexus analyze --default-branch develop # 生成的回归对比示例中使用的分支(base_ref)
gitnexus analyze --verbose # 在解析器不可用时记录跳过的文件
gitnexus analyze --worker-timeout 60 # 增加慢解析的工作线程空闲超时
gitnexus analyze --workers <n> # 解析工作线程池大小(>=1;默认:核心数-1,上限 16,
# 根据仓库自动调整大小)。0 会被拒绝 —— 没有顺序模式。
gitnexus analyze --wal-checkpoint-threshold 67108864 # LadybugDB WAL 自动检查点阈值(字节)
# (默认 67108864 = 64
_[原 README 过长已截断]_