codexray 🔦

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

Why

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.

Highlights

• ⚡ 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.

Quickstart

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 sdk

CLI

codexray 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)

Use it from your AI agent

Point any MCP client at codexray-mcp:

<details> <summary><b>Claude Code</b></summary>

claude mcp add codexray -- codexray-mcp --root /path/to/your/project

</details>

<details> <summary><b>opencode</b> — <code>~/.config/opencode/opencode.json</code></summary>

{
  "mcp": {
    "codexray": {
      "type": "local",
      "command": ["codexray-mcp", "--root", "/path/to/your/project"]
    }
  }
}

</details>

<details> <summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

{
  "mcpServers": {
    "codexray": {
      "command": "codexray-mcp",
      "args": ["--root", "/path/to/your/project"]
    }
  }
}

</details>

Tools exposed: index_repository, search_symbols, file_outline, find_references, get_index_stats.

Python API

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"))

How it works

┌────────────────────────────┐         ┌──────────────────────────────┐
│  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.

Project layout

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

Status & roadmap

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 tagged function, not method
• Macros can confuse brace matching; templates only partially understood
• References are identifier-level, not resolved across scopes/overloads
• No incremental re-index yet (index_repository rebuilds)

Ideas welcome — tree-sitter backends, watch-mode incremental updates, more languages, persisted indexes. Open an issue!

Development

make test          # build + pytest
python -m pytest tests/ -v

License

MIT © 2026 akashmark8-cloud