CodeRay — X-ray your codebase
CodeRay builds a local code index that gives AI agents a smarter way to explore a codebase — reading only what they need, not whole files.
Runs locally. No LLM. No network. No API key.
The problem
AI agents exploring a codebase default to reading whole files – even when one function is all that's needed. Every unnecessary line burns tokens and floods the context window: driving up API costs and noise with every read.
The root cause is simple: agents know the file paths but no finer location. Without knowing where in a file something lives, they have no choice but to read everything.
CodeRay fixes this. Every tool returns file paths with exact line ranges — so agents locate first, then read only the lines that matter.
How it works
CodeRay exposes three primitives, each returning paths + line ranges:
| Tool | Question it answers | What agents get |
|---|---|---|
| search | Where is the code that does X? | Relevant chunks with file paths and line ranges |
| skeleton | What's the shape of this file? | Signatures + docstrings only, each tagged with its line range |
| impact | What breaks if I change this? | Callers, imports, and inheritors — located by line range |
The two-phase flow
- Locate — run
search,skeleton, orimpactto find what's needed. Every result includes a file path and a symbol-level line range. - Read precisely — use those line ranges to load only the relevant snippet. Skip the rest.
This keeps context windows lean and agent reasoning focused. CodeRay is not a replacement for grep — it fills the gap when exact names are unknown or a map is needed before reading.
Token savings (tiktoken, cl100k_base)
| File | Lines | Full read | Skeleton | Savings | % reduction |
|---|---|---|---|---|---|
src/coderay/graph/impact.py |
249 | 2,333 | 693 | 3.4× | 70% |
src/coderay/cli/commands.py |
584 | 4,327 | 1,906 | 2.3× | 56% |
src/coderay/pipeline/indexer.py |
408 | 3,065 | 1,433 | 2.1× | 53% |
| Query | Search hit tokens | vs full indexer.py read |
|---|---|---|
| "how are files re-indexed on change" | 479 | ~6x cheaper |
Tools
Semantic search
Agents search by meaning, not by name — useful when the exact function or class is unknown. Results return file paths with line ranges pointing at relevant chunks. Treat them as candidates: confirm with skeleton or a ranged read before acting. Keep the index fresh with coderay watch or coderay build when the tree drifts.
Blast radius
Shows callers, imports, and inheritance for a symbol before it changes. Each result is tied to a file path and line range — combine with skeleton or ranged reads on those locations when bodies are needed.
Skeleton
Returns signatures and docstrings only — no function bodies. Every block is tagged with its path and line range so subsequent reads can be scoped to exactly those lines. A full file read should happen only when the skeleton isn't enough.
Full read
Same file, raw source — for comparison:
First run
coderay init and coderay build.
Status — coderay status: chunks, branch, commit, schema.
MCP
Same three tools over MCP: search, skeleton (paths and line ranges), and impact—so AI agents can narrow context before full-file reads. Point the server at a checkout whose root contains .coderay.toml (CODERAY_REPO_ROOT below). For tool choice versus a plain read, see AGENTS.md.
which coderay-mcp
{
"mcpServers": {
"coderay": {
"command": "/path/to/.venv/bin/coderay-mcp",
"args": [],
"env": { "CODERAY_REPO_ROOT": "${workspaceFolder}" }
}
}
}
CODERAY_REPO_ROOT must be the directory that contains .coderay.toml. More detail: mcp_server/README.md.
Features
- Languages — Python, JavaScript, and TypeScript —
parsing/README.md - Multi-repo / monorepo — roots, aliases, optional
includesubtrees —core/README.md - Hybrid search — vector + BM25 (RRF), optional boosting —
retrieval/README.md - Embeddings — fastembed (CPU) or MLX on Apple Silicon; defaults to MiniLM L6 for speed — configure BGE in
.coderay.tomlfor stronger (heavier) vectors —embedding/README.md - Watch — incremental re-index;
.coderay.tomlis the source of truth for what’s indexed
Install
pipx (no venv):
brew install pipx && pipx install coderay # macOS
# Linux: python3 -m pip install --user pipx && pipx install coderay
In a project:
python -m venv .venv && source .venv/bin/activate
pip install coderay
# Apple Silicon (optional): pip install "coderay[mlx]"
From source: pip install -e ".[all]" — see CONTRIBUTING.md.
Quick start
cd /path/to/your/project
coderay init
coderay watch
coderay search "how does authentication work"
coderay skeleton src/app/main.py
coderay impact some_symbol
CLI
| Command | Description |
|---|---|
coderay init |
Create .coderay.toml and .coderay/ |
coderay watch [--quiet] |
Re-index on file changes |
coderay build [--full] |
One-off or full rebuild |
coderay search "query" |
Semantic search (--top-k, --path-prefix, --no-tests) |
coderay skeleton FILE |
Signatures (--symbol) |
coderay impact SYMBOL |
Blast radius (--max-depth) |
coderay graph |
List edges (--from, --to, --kind) |
coderay list |
Chunks or per-file summary |
coderay status |
Index metadata |
coderay maintain |
Compact LanceDB |
Configuration
coderay init writes an annotated .coderay.toml: [index], [search], [graph], [embedder], [watcher]. See module READMEs linked from src/README.md.
Contributing
Accuracy and limitations
Semantic search is approximate (model and chunks matter). No warranty — MIT License. Evaluate on your own codebase.
Metadata
Release files for coderay 1.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| coderay-1.2.2.tar.gz | 96.2 kB | With provenance | Details for coderay-1.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| coderay-1.2.2-py3-none-any.whl | Python 3 | none | any | Details for coderay-1.2.2-py3-none-any.whl |
Total release size: 221.3 kB
Release files / coderay-1.2.2.tar.gz
| Download URL | coderay-1.2.2.tar.gz |
|---|---|
| Size | 96.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3502553487df21a82d1cb731b38d9a92561bfd658639d84b5841d701052cda26
|
|
BLAKE2b-256 checksum How to use checksums |
64791fc3fb3e2c85fde19fe6f9bbf2c4714ff964ff8605b91b0217847498e02c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logRelease files / coderay-1.2.2-py3-none-any.whl
| Download URL | coderay-1.2.2-py3-none-any.whl |
|---|---|
| Size | 125.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61439bd88c2ef755b7c20579cb6410b16cd53db45342da5a6ce1b4983e39d468
|
|
BLAKE2b-256 checksum How to use checksums |
6032e903c194359a443ec9b11abbbb74b07068276dec07ae43301c443dd6062b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logSecurity for coderay 1.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for coderay-1.2.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.