AI导哈

代码语义图谱工具

CodeXRay是一个零配置、本地的代码语义知识图谱工具，通过构建代码的AST语义图谱，帮助AI编程代理减少30%以上的token消耗和25%以上的工具调用。

  • by NeuralRays
  • TypeScript
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 NeuralRays/codexray

使用说明

CodeXRay

代码库的X射线视觉 --节省人工智能编码代理的语义知识图 30%+代币 和 25%以上的工具调用.零配置，零API密钥，100%本地。

一 codexray_context 调用将替换5-10次文件读取。 您的AI代理查询预先构建的知识图，而不是逐一扫描文件。

See the token savings in action

没有CodeXRay（典型的克劳德代码会话）

You: "Fix the authentication bug in the login flow"

Claude Code:
  1. grep "auth" across codebase          →  800 tokens
  2. Read auth/middleware.ts               → 1,200 tokens
  3. Read auth/service.ts                  → 1,500 tokens
  4. Read auth/types.ts                    →   600 tokens
  5. grep "login" across codebase          →   700 tokens
  6. Read routes/login.ts                  → 1,100 tokens
  7. Read utils/jwt.ts                     →   900 tokens
  8. Read tests/auth.test.ts              → 1,400 tokens
  9. grep "validateToken"                  →   500 tokens
  10. Read middleware/validate.ts           → 1,000 tokens
  ─────────────────────────────────────────────────
  Total: 10 tool calls, ~9,700 tokens just to FIND the code

使用CodeXRay（相同任务）

You: "Fix the authentication bug in the login flow"

Claude Code:
  1. codexray_context("authentication login bug")
     → Returns all relevant symbols, code snippets,
       call relationships, and file locations
  ─────────────────────────────────────────────────
  Total: 1 tool call, ~2,000 tokens — ready to fix

结果：令牌减少80%，查找相关代码的工具调用减少90%。

┌─────────────────────────────────────────────┐
│           Claude Code / Cursor              │
│                                             │
│   "Fix the authentication bug"              │
│           │                                 │
│    ┌──────▼──────┐   ┌──────────────┐       │
│    │ Explore Agent│───│ Explore Agent│       │
│    └──────┬───────┘   └──────┬──────┘       │
└───────────┼──────────────────┼──────────────┘
            │                  │
     ┌──────▼──────────────────▼──────┐
     │     CodeXRay MCP Server        │
     │                                │
     │  16 tools • TF-IDF search      │
     │  Call graph • Impact analysis   │
     │  Dead code • Circular deps     │
     │  Complexity • Path finding     │
     │                                │
     │       ┌─────────────┐          │
     │       │ SQLite Graph│          │
     │       │ + FTS5      │          │
     │       │ + TF-IDF    │          │
     │       └─────────────┘          │
     └────────────────────────────────┘

快速开始

任何包管理器

# Zero-install (recommended)
npx codexray

# npm
npm install -g codexray

# pnpm
pnpm add -g codexray

# yarn
yarn global add codexray

# bun
bun add -g codexray

Claude代码的一个命令设置

npx codexray

交互式安装程序：

  1. ✅ 在中配置MCP服务器 ~/.claude.json
  2. ✅ 为所有16个CodeXRay工具设置自动允许权限
  3. ✅ 自动检测Windows并应用 cmd /c 包裹
  4. ✅ 初始化并索引当前项目
  5. ✅ 构建TF-IDF语义搜索索引
  6. ✅ 写 CLAUDE.md 附有工具使用说明
  7. ✅ 安装git挂钩以实现自动同步

重新启动Claude代码 并且它自动工作。

手动设置

codexray init --index     # Initialize + index
cxr init -i               # Short alias

为什么选择CodeXRay？

  • 省钱 -代币减少30%以上意味着API成本降低
  • 更快的响应 --AI代理通过图形查询而不是扫描文件立即找到代码
  • 更高的准确度 --语义搜索理解 意义，而不仅仅是关键字
  • 零配置 — npx codexray 并且完成了。没有API密钥，没有云，没有可下载的ML模型
  • 轻量级 --约50MB，而基于嵌入的替代方案约500MB
  • 私人 --100%本地。你的代码永远不会离开你的机器

运作原理

  1. 索引 --Tree sitter将代码解析为AST，将每个函数、类、方法、类型及其关系提取到具有TF-IDF语义索引的SQLite图中
  2. 查询 --Claude Code通过16个MCP工具查询图形，而不是扫描文件
  3. 同步 --Git钩子在每次提交时都会保持索引最新

无CodeXRay

AI agent: "Fix auth bug" → grep → read file → grep → read file → read file → ...
         15+ tool calls just to FIND the relevant code

使用CodeXRay

AI agent: "Fix auth bug" → codexray_context("auth bug") → all relevant code + relationships
         1 tool call — immediately start fixing

16个MCP工具

初级（先使用）

工具 说明
codexray_overview 项目结构、语言、关键符号
codexray_context 带有代码片段的任务相关上下文
codexray_search 按名称/关键字查找符号（FTS5）
codexray_semantic 查找代码 意义 （TF-IDF）

探索

工具 说明
codexray_node 详细的符号信息+完整的源代码
codexray_callers 谁叫这个符号？
codexray_callees 这个符号叫什么？
codexray_deps 完全依赖树
codexray_path 两个符号之间的最短连接

分析

工具 说明
codexray_impact 爆炸半径（递归BFS）
codexray_hotspots 大多数连接/关键符号
codexray_deadcode 查找未使用的函数/类
codexray_circular 检测循环依赖关系
codexray_complexity 高圈复杂度函数
codexray_files 带有统计信息的索引文件树
codexray_status 指数健康检查

CLI参考

codexray                  # Interactive Claude Code installer
codexray install          # Same (explicit)
codexray init [path]      # Initialize project
  -i, --index             # Index immediately
  --no-hooks              # Skip git hook
  --claude-md             # Write CLAUDE.md
codexray index [path]     # Full index + semantic build
  -f, --force             # Force re-index
  -q, --quiet             # No output
codexray sync [path]      # Incremental sync
codexray watch [path]     # Real-time file watching
codexray status [path]    # Index statistics
codexray query <q>        # FTS5 search from CLI
codexray semantic <q>     # TF-IDF semantic search from CLI
codexray context <q>      # Build context from CLI
codexray overview [path]  # Project overview
codexray hooks <action>   # install/remove/status
codexray serve [path]     # Start MCP server (stdio)
codexray uninstall        # Remove from Claude Code

短别名： cxr 适用于所有命令。

15种支持的语言

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin——所有这些都使用树形图进行解析，以准确提取AST。

主要特点

🧠 语义搜索（TF-IDF）

搜索“身份验证”并查找 login, validateToken, AuthService --即使命名不同。没有API密钥，没有外部服务，没有可下载的嵌入模型。纯本地TF-IDF，带有camelCase/snake_case分割，按名称/签名/docstring加权。

🔍 智能上下文构建

一 codexray_context 调用将替换5-10次文件读取。从任务描述中提取关键字，通过FTS5+TF-IDF查找匹配的符号，在依赖关系图中展开，按相关性评分，并返回带有调用关系的代码片段。

💀 死码检测

codexray_deadcode 查找从未被调用或引用的函数、方法和类。

🔥 热点分析法

codexray_hotspots 标识连接最多的符号——最高的调用者+依赖关系。这些变化的风险最大。

💥 爆炸半径分析

codexray_impact 使用BFS跟踪所有可传递的调用者，按深度分组。

🔄 循环依赖检测

codexray_circular 使用DFS查找导入/调用周期。

📐 复杂度分析

codexray_complexity 查找超过圈复杂度阈值的函数。

🛤️ 向导

codexray_path 通过BFS找到任意两个符号之间的最短连接。

👁 观看模式

codexray watch 使用chokidar进行实时索引同步，消除300ms的抖动。

⚡ Git挂钩

提交后挂钩自动同步索引。零维护。

🖥️ 交叉平台的

macOS、Linux、Windows。Windows自动运行 cmd /c 包装。

库API

import CodeXRay from 'codexray';

// Initialize and index
const cxr = await CodeXRay.init('/path/to/project', { index: true });

// FTS5 search
const results = cxr.search('UserService');

// Semantic search
const semantic = cxr.semanticSearch('user authentication flow');

// Call graph
const callers = cxr.getCallers(results[0].id);
const callees = cxr.getCallees(results[0].id);

// Path finding
const path = cxr.findPath(results[0].id, results[1].id);

// Impact analysis
const impact = cxr.getImpact(results[0].id);

// Smart context
const context = cxr.buildContext('fix login authentication bug');
console.log(cxr.formatContext(context));

// Analysis
const dead = cxr.findDeadCode();
const hotspots = cxr.findHotspots(10);
const cycles = cxr.findCircularDeps();
const complex = cxr.getComplexityReport(15);
const stats = cxr.getStats();

cxr.close();

配置

.codexray/config.json:

{
  "version": 1,
  "projectName": "my-app",
  "exclude": ["node_modules/**", "dist/**"],
  "maxFileSize": 1048576,
  "gitHooksEnabled": true
}

需求

  • Node.js 18-24 （用于本地获取、glob、ES2022）
  • 没有API密钥，没有云服务，没有外部数据库
  • 100%本地-一切尽在 .codexray/graph.db

CodeXRay与CodeGraph

功能 CodeGraph CodeXRay
MCP工具 7 16
语义搜索 向量嵌入（需要transformers.js ~ 500MB） TF-IDF （零存款，即时）
死码检测 ❌ ✅
热点分析 ❌ ✅
循环依赖检测 ❌ ✅
复杂性分析 ❌ ✅
符号之间的路径查找 ❌ ✅
监视模式（实时） ❌ ✅
项目概述工具 ❌ ✅
文件树工具 ❌ ✅
依赖树工具 ❌ ✅
框架检测（React） ❌ ✅
窗户 cmd /c 自动包装 ❌ ✅
cxr 短别名 ❌ ✅
卸载命令 ❌ ✅
库API ❌ ✅
Node.js要求 18+ 18+
零配置 npx 安装 ✅ ✅
语言 13 15
安装大小 ~500MB（transformers.js） ~50MB

贡献者


NeuralRays
Creator & Maintainer
Claude
AI Pair Programmer

许可证

麻省理工学院

Report a Bug  ·  Request a Feature  ·  Submit a PR  ·  Discussions  ·  npm Package

If you find CodeXRay useful, please consider giving it a star on GitHub!

相关 MCP