# codexray 🔦

**X-ray vision for your codebase — a fast C++ symbol indexer exposed as an [MCP](https://modelcontextprotocol.io) server for AI coding agents.**

[![CI](https://github.com/akashmark8-cloud/codexray/actions/workflows/ci.yml/badge.svg)](https://github.com/akashmark8-cloud/codexray/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![C++17](https://img.shields.io/badge/core-C%2B%2B17-00599C)
![Python](https://img.shields.io/badge/interface-Python%203.10+-3776AB)

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](https://modelcontextprotocol.io), 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.

```bash
git clone https://github.com/akashmark8-cloud/codexray && cd codexray
make                       # builds build/libcodexray.so
pip install -e ".[dev]"    # python package + mcp sdk
```

### CLI

```bash
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>

```bash
claude mcp add codexray -- codexray-mcp --root /path/to/your/project
```
</details>

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

```json
{
  "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>

```json
{
  "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

```python
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

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

## License

MIT © 2026 akashmark8-cloud