iohub/codexray
Free仓库感知的本地 MCP，用混合语义 + 全文检索引擎实时理解代码库，按需为 AI 提供相关代码上下文。兼容 Claude Code 与 Codex。
FreeFree tier
About iohub/codexray
CodeXray is an open-source, repository-aware local MCP (Model Context Protocol) server that understands your codebase in real time using a hybrid semantic and full-text search engine. It builds a 4D knowledge graph combining call graphs, code vectors, commit vectors, and knowledge vectors, powered by Tree-sitter AST parsing for seven programming languages. Features include real-time incremental indexing (MD5 diff-based), automatic MCP registration for Claude Code and Codex CLI, and a local-first design with zero daemon and zero configuration overhead. It supports semantic search via dense vector embeddings with fallback to graph search when an embedding API is unavailable, and fuses results using RRF and Cross-Encoder reranking for high precision.
Key Features
Hybrid Search Engine combining dense vector search (semantic) and BM25 full-text search, fused via RRF and reranked by Cross-Encoder
4D Knowledge Graph integrating call graph (via Tree-sitter AST), code vectors, commit vectors, and knowledge vectors
Real-time Incremental Indexing: full build on first run, MD5 diff for subsequent runs, auto-indexing on startup, and runtime file change watching
Native MCP stdio protocol designed for Claude Code and Codex CLI — zero daemon, zero config, auto-registration on install
Local-first: all code and data stay on the machine, no SaaS required; works offline for graph search
Fallback to graph search when embedding API is unavailable, ensuring uninterrupted use
Supports 7 programming languages via Tree-sitter AST (functions, classes, methods)
Auto-cleans orphaned embeddings to prevent index bloat
Pros & Cons
Pros
- Open source and free with no licensing costs
- Local-first design ensures code never leaves the machine, enhancing privacy and security
- Real-time incremental indexing minimizes overhead after initial build
- Works offline for call graph and name search; graceful fallback when embedding API is unavailable
- Seamless integration with Claude Code and Codex CLI via auto-registration
- Zero daemon and zero configuration — starts and exits with the AI coding tool
- Supports multiple languages and provides rich knowledge graph (calls, commits, knowledge)
Cons
- Requires an external embedding API for full semantic search; without it, search is limited to graph-based matching
- Initial full-index build can be time-consuming for very large repositories
- Only supports 7 languages via Tree-sitter AST; less common languages are not covered
- Documentation is limited to the GitHub README; no dedicated website or extensive guides
Best For
Providing relevant code context to AI assistants like Claude Code and Codex CLI for code generation and debuggingSearching code by intent (e.g., 'login logic' finds authenticateUser) using hybrid semantic and full-text searchExploring function/class dependencies and call graphs within a codebaseReal-time incremental indexing for large, actively developed repositoriesPrivate, local code search without sending code to external services
FAQ
How do I install CodeXray?
The recommended method is one curl command: curl -fsSL https://raw.githubusercontent.com/iohub/codexray/main/install.sh | sh. It auto-detects your OS and architecture, downloads the binary, and registers the MCP server. Restart Claude Code after installation.
What languages does CodeXray support?
CodeXray uses Tree-sitter AST to parse seven programming languages for building call graphs and extracting functions, classes, and methods. The specific languages are not enumerated in the README but are typical Tree-sitter supported languages (e.g., Python, JavaScript, TypeScript, Rust, Go, etc.).
Does CodeXray require an internet connection?
For full semantic search, an embedding API is required, which may need internet access. However, call graph and name search work offline without any configuration, and the system gracefully falls back to graph search when the embedding API is unavailable.
How does CodeXray handle indexing updates?
Indexing is incremental: on first run it performs a full build. Subsequent runs compare MD5 hashes of source files and only re-process changed files. It also auto-indexes on MCP startup and watches file changes during runtime, and cleans up orphaned embeddings to prevent bloat.