codexray (Neural Rays)

CodeXRay

](https://www.npmjs.com/package/codexray)  ](https://nodejs.org/)   ](https://github.com/NeuralRays/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工具

初级（先使用）

探索

分析

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         # FTS5 search from CLI
codexray semantic      # TF-IDF semantic search from CLI
codexray context       # Build context from CLI
codexray overview [path]  # Project overview
codexray hooks    # 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

贡献者

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!