Codexray

CodeXray

Code search & knowledge engine for the AI era. Semantic + full-text hybrid search, real-time indexing, call graph + code vectors + commit vectors + knowledge vectors — unified into one native MCP server.

> Built natively for Claude Code/Codex CLI — zero daemon, zero config overhead.

> 📖 [中文文档](README.zh.md)

Highlights

🧠 Hybrid Search Engine — Semantic + Full-Text Dual Channel

Goes beyond keyword matching. Dense vector search understands code intent ("login logic" → authenticateUser), while BM25 full-text search locks in exact matches. Results are fused via RRF and re-ranked by Cross-Encoder for precision. When embedding API is unavailable, gracefully falls back to graph search — never breaks.

🔗 4D Knowledge Graph

Call graph + code vectors + commit vectors + knowledge vectors — four dimensions of codebase awareness. Tree-sitter AST parses 7 languages to build complete function/class/method relationships:

• Who calls this function?
• What does this function depend on?
• Find code by describing what it does

⚡ Real-time Incremental Indexing

Full build on first run, only re-processes changed files thereafter (MD5 diff). Auto-indexes on MCP startup and watches file changes during runtime. Auto-cleans orphaned embeddings — index never bloats.

🔌 Native MCP, Local-First

Built specifically for Claude Code/Codex CLI MCP stdio protocol. Install registers MCP automatically — no manual config, no persistent daemon. Starts and exits with Claude Code, zero residue. All code and data stay local, no SaaS required.

Quick Start

Recommended — one curl command

curl -fsSL https://raw.githubusercontent.com/iohub/codexray/main/install.sh | sh

Auto-detects OS/arch/libc, downloads, installs, and registers MCP. Restart Claude Code after — done.

First run: codexray install auto-launches an interactive setup wizard for the embedding API (graph search works without configuration). CodeXray works out of the box for call graph and name search.

Manual download (Linux musl example)

curl -L -o codexray.tar.gz https://github.com/iohub/codexray/releases/latest/download/codexray-linux-x64-musl.tar.gz
tar -xzf codexray.tar.gz
./codexray install && rm codexray.tar.gz

Other platforms: replace linux-x64-musl with darwin-arm64, darwin-x64, or linux-x64 from the latest release.

From source

git clone https://github.com/iohub/codexray.git && cd codexray
cargo build --release && ./rust-core/target/release/codexray install

How It Works

Index Building

Source files
  → Tree-sitter AST parse (7 languages)
  → Extract functions / classes / methods
  → Build call graph (PetCodeGraph)
  → Batch embed via API (SQLite cache)
  → Store vectors in LanceDB
  → Build BM25 index in Tantivy
  → Save to ~/.codexray//

Idempotent: index builds are incremental — the first run is a full build, subsequent runs compare MD5 hashes and only re-process changed files.

Hybrid Search Pipeline (CodeXray search)

                        ┌─────────────────────┐
User query ────────────→│  Embedding Model     │──→ Query vector
                        └─────────────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          ▼                       ▼                       ▼
   ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
   │ Dense Search │       │ Sparse Search│       │ Graph Search │
   │ (LanceDB ANN)│       │ (Tantivy BM25)│      │ (PetCodeGraph)│
   └──────┬───────┘       └──────┬──────┘       └──────┬──────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 ▼
                        ┌─────────────────┐
                        │   RRF Fusion    │  ← Reciprocal Rank Fusion
                        │  (Top-20 candidates)│
                        └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │    Reranker     │  ← Cross-Encoder fine re-ranking
                        │ (Qwen3-Reranker)│     scores each (query, code) pair
                        └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │   Final Results  │  ← Top-5 (or Top-N)
                        └─────────────────┘

| Stage | Technology | Role | |-------|-----------|------| | Dense Search | LanceDB + Embedding Model | Semantic vector similarity | | Sparse Search | Tantivy BM25 | Keyword & token matching | | RRF Fusion | Reciprocal Rank Fusion | Merge heterogeneous scores fairly | | Reranker | Cross-Encoder (Qwen3-Reranker-4B) | Full-interaction precision scoring | | Fallback | PetCodeGraph | Graph-based name search (no API needed) |

If embedding/reranker are unavailable, the pipeline falls back gracefully to graph-based name search and BM25-only mode.

Auto-Indexing Modes

| Mode | When | Trigger | |------|------|---------| | MCP server | On startup + file changes | codexray install + restart Claude Code |

The MCP server automatically indexes on startup, watches file changes during runtime, and injects CLAUDE.md for tool discovery.

Storage

• Config: ~/.codexray/config.json (global, shared across all projects)
• Index: ~/.codexray//
• project.json — Project metadata
• graph.bin — Serialized call graph
• embeddings.lance/ — LanceDB vector data
• tantivy_bm25/ — BM25 full-text index
• file_hashes.json — MD5 incremental tracking
• embedding_hashes.json — Embedding incremental tracking

No daemon, no HTTP server. Every CLI command is a standalone process.

Supported Languages

| Language | Functions | Structs/Classes | Call Graph | |----------|:---------:|:---------------:|:----------:| | Rust | ✅ | ✅ | ✅ | | Python | ✅ | ✅ | ✅ | | JavaScript | ✅ | ✅ | ✅ | | TypeScript | ✅ | ✅ | ✅ | | Go | ✅ | ✅ | ✅ | | C/C++ | ✅ | ✅ | ✅ | | Java | ✅ | ✅ | ✅ |

Configuration

~/.codexray/config.json:

{
  "embedding": {
    "provider": "openai-compatible",
    "model": "Qwen/Qwen3-Embedding-4B",
    "api_token": "sk-...",
    "api_base_url": "https://api.siliconflow.cn/v1",
    "dimensions": 2560
  },
  "index": {
    "min_code_block_length": 16,
    "enable_reranker": true,
    "hybrid": {
      "enable_bm25": true,
      "bm25_top_k": 100,
      "vector_top_k": 100,
      "rrf_k": 60,
      "rrf_top_k": 20,
      "short_code_threshold": 30,
      "short_code_penalty": 0.5
    },
    "reranker": {
      "enabled": true,
      "model": "Qwen/Qwen3-Reranker-4B",
      "api_token": "sk-...",
      "api_base_url": "https://api.siliconflow.cn/v1/rerank",
      "top_n": 5,
      "candidate_multiplier": 5,
      "timeout_secs": 60
    }
  },
  "installed_hooks": {}
}

Model Roles

| Model | Role | When | |-------|------|------| | Qwen/Qwen3-Embedding-4B | Converts code → vectors for dense search | Index building | | Qwen/Qwen3-Reranker-4B | Scores (query, code) pairs for precision | Search time |

Set via the interactive wizard on first run, or create manually. If embedding API is unavailable, graph-based search still works.

Development

cd rust-core

# Build
cargo build

# Build release
cargo build --release

# Run tests
cargo test

# Run specific test
cargo test test_build_graph_functionality -- --nocapture

License

MIT

Built with: Tree-sitter · Petgraph · LanceDB · Tantivy · Tokio · Clap · Axum

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: iohub
• Source: iohub/codexray
• License: MIT

Install and usage instructions live in the source repository linked above.