Skip to main content
Glama
Sign In
codexray

codexray

by akashmark8-cloud
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

codexray 🔦

X-ray vision for your codebase — a fast C++ symbol indexer exposed as an MCP server for AI coding agents.

CI License: MIT C++17 Python

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.

Related MCP server: codebase-rag

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:

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

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Sigil MCP Server

      Superuser666-Sigil
      A
      license
      Not graded
      quality
      D
      maintenance
      Provides IDE-like code navigation and search for local repositories, enabling AI assistants to perform symbol search, trigram indexing, and semantic navigation.
      AGPL 3.0

    • codebase-rag

      Ar-maan05
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.
      4
      MIT

    • sonde

      anishmoncivarghese
      A
      license
      Not graded
      quality
      B
      maintenance
      Indexes a codebase into a symbol-level graph and exposes tools for finding symbols, querying relationships, and assessing impact, letting AI coding agents answer structural questions in a single call within a token budget.
      83 npm
      4
      Apache 2.0

    • MCP Codebase Server

      tolstikov-dev
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to semantically navigate codebases via an AST index, supporting symbol search, usage lookup, module exploration, and dependency analysis.
      MIT