X-ray vision for your codebase — a fast C++ symbol indexer exposed as an MCP server for AI coding agents.
Give your coding agent instant, whole-repo symbol awareness without running a language server:
$ codexray search conn --root ./myproject
950 method 42 onConnect src/net/server.cpp
870 function 18 connect_db src/db/pool.cpp
AI agents working in large repos waste tokens grepping blindly or re-deriving structure.
codexray answers the three questions agents ask most, in milliseconds:
- "Where is this symbol?" → fuzzy
search_symbols - "What's in this file?" →
file_outline - "Where else is it used?" →
find_references
It speaks Model Context Protocol, so Claude Code, opencode, Cursor, Codex CLI, Windsurf and friends can use it as a tool — no plugins, no LSP server, no config soup.
- ⚡ C++17 core, zero external dependencies — single translation unit, ~1100 LOC
- 🐍 Python interface via
ctypes(no pybind11 build headaches) - 🔌 MCP server out of the box (
codexray-mcp) - 🧭 Fuzzy search:
gret→Greeter,onConnect; exact > prefix > substring > subsequence scoring - 📚 5 languages today: C/C++, Python, JavaScript/TypeScript, Go, Rust
- 📖 References index: every identifier occurrence, definitions flagged
- 🪶 No daemon, no database — an index is just memory; rebuild is cheap
Measured on a laptop (AMD Ryzen): 25,395 system headers · 6.5M lines · 364k symbols · 9.8M references indexed in ~29 s (~225k lines/s), fuzzy search over all symbols in <100 ms.
Requires: a C++ compiler (g++ or clang++) and Python ≥ 3.10.
git clone https://github.com/akashmark8-cloud/codexray && cd codexray
make # builds build/libcodexray.so
pip install -e ".[dev]" # python package + mcp sdkcodexray stats --root path/to/repo # what got indexed
codexray search Widget --root path/to/repo # fuzzy symbol search
codexray outline src/main.rs # file outline
codexray refs main # references (defs flagged *)
codexray serve --root path/to/repo # run the MCP server (stdio)Point any MCP client at codexray-mcp:
Claude Code
claude mcp add codexray -- codexray-mcp --root /path/to/your/projectopencode — ~/.config/opencode/opencode.json
{
"mcp": {
"codexray": {
"type": "local",
"command": ["codexray-mcp", "--root", "/path/to/your/project"]
}
}
}Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"codexray": {
"command": "codexray-mcp",
"args": ["--root", "/path/to/your/project"]
}
}
}Tools exposed: index_repository, search_symbols, file_outline,
find_references, get_index_stats.
from codexray import CodeIndex
idx = CodeIndex()
idx.add_tree("./myproject")
for hit in idx.search("connect", limit=5):
print(hit["kind"], hit["name"], f'{hit["path"]}:{hit["line"]}')
print(idx.outline("src/server.cpp"))
print(idx.references("Server"))┌────────────────────────────┐ ┌──────────────────────────────┐
│ your repo │ │ AI agent (Claude Code, │
│ .cpp .py .ts .go .rs ... │ │ opencode, Cursor, Codex…) │
└─────────────┬──────────────┘ └──────────────▲───────────────┘
│ os.walk + read │ MCP (stdio)
┌─────────────▼──────────────┐ ┌──────────────┴───────────────┐
│ C++ core (libcodexray) │◀──ctypes│ Python layer │
│ • tokenizer (comments, │ │ • tree walker + excludes │
│ strings, raw strings) │ │ • CodeIndex high-level API │
│ • heuristic def scanner │ │ • FastMCP-style tool server │
│ • scope/end-line tracker │ └──────────────────────────────┘
│ • fuzzy scorer │
│ • JSON output │
└────────────────────────────┘
One pass per file builds two indexes: a symbol table (name, kind, span, signature) and a reference map (identifier → occurrences). Search scores candidates by exact / prefix / substring / word-boundary-subsequence match with gap penalties.
src/cpp/codexray.h C API (usable from any FFI-capable language)
src/cpp/codexray.cpp the entire native core
src/codexray/_native.py ctypes bindings
src/codexray/index.py CodeIndex (tree walking, excludes, summaries)
src/codexray/server.py MCP server (5 tools)
src/codexray/cli.py command-line interface
tests/ pytest suite
examples/demo/ polyglot sample project
This is a young project — the parser is intentionally heuristic (fast, dependency-free) rather than a full AST. It handles real-world code well but not everything. Known limitations:
- Out-of-line C++ member definitions (
void Widget::set(...)) are taggedfunction, notmethod - Macros can confuse brace matching; templates only partially understood
- References are identifier-level, not resolved across scopes/overloads
- No incremental re-index yet (
index_repositoryrebuilds)
Ideas welcome — tree-sitter backends, watch-mode incremental updates, more languages, persisted indexes. Open an issue!
make test # build + pytest
python -m pytest tests/ -vMIT © 2026 akashmark8-cloud