<div align="center">
<img src="leindex.jpeg" alt="LeIndex" width="500"/>
[](https://www.rust-lang.org/)
[](LICENSE)
[](https://modelcontextprotocol.io)
</div>
# LeIndex
**Understand large codebases instantly.**
LeIndex is a semantic code search engine that lets you search code by **meaning**, not just keywords.
Instead of hunting through files with grep or hoping variable names match your query, you can ask things like:
- *"Where is authentication enforced?"*
- *"Where are API tokens validated?"*
- *"How does session management work?"*
LeIndex surfaces the actual implementation — even if the words you're searching for never appear in the code.
Built in Rust. Built for developers and AI coding tools.
---
## Demo: finding logic that grep and LLMs miss
Imagine a codebase where authentication is implemented like this:
```rust
fn validate_session(req: Request) -> Result<User> { ... }
fn verify_token(token: &str) -> bool { ... }
fn authorize_user(user: &User, action: Action) -> bool { ... }
```
None of these functions contain the word **"authentication"**.
### grep
```bash
grep -r "authentication" src/
# (no matches)
```
### LeIndex
```bash
leindex search "where is authentication enforced"
```
```
src/security/session_validator.rs validate_session (0.92)
src/auth/token_verifier.rs verify_token (0.87)
src/middleware/auth_gate.rs authorize_user (0.84)
```
LeIndex finds the correct logic because it searches by **semantic intent**, not string matches.
It works across multiple repositories too:
```bash
leindex search "where are API rate limits enforced"
```
```
gateway/middleware/rate_limit.rs throttle_request (0.91)
api/server/request_throttle.go limit_handler (0.88)
auth/session_policy.rs enforce_policy (0.83)
```
---
## 90%+ Token Savings for AI Coding Tools
When an LLM reads your code with standard tools, it burns tokens on entire files just to understand one function. LeIndex returns **only what matters** — structured, context-aware results instead of raw file dumps.
| Understand a 500-line file | ~2,000 tokens | ~380 tokens | **81%** |
| Find all callers of a function | ~5,800 tokens | ~420 tokens | **93%** |
| Navigate project structure | ~8,500 tokens | ~650 tokens | **92%** |
| Cross-file symbol rename | ~12,000 tokens | ~340 tokens | **97%** |
Every tool call is **context-aware** — not atomic. When you look up a symbol, you don't just get its definition. You get its callers, callees, data dependencies, and impact radius. When you summarize a file, you get cross-file relationships that `Read` can never provide at any token cost. One LeIndex call replaces chains of `Grep → Read → Read → Read`.
> See [full benchmarks](docs/TOOL_SUPREMACY_BENCHMARKS.md) for methodology and detailed comparisons.
---
## Quick Start (2 minutes)
### Install
**Via cargo (recommended):**
```bash
cargo install leindex
```
**Via install script:**
```bash
curl -fsSL https://raw.githubusercontent.com/scooter-lacroix/leindex/master/install.sh -o install-leindex.sh
bash install-leindex.sh
```
**Environment Variables:**
| `LEINDEX_HOME` | No | Override storage/index home directory | `~/.leindex` |
| `LEINDEX_PORT` | No | Override HTTP server port | `47268` |
### Index and search
```bash
# Index your project
leindex index /path/to/project
# Search by meaning
leindex search "authentication flow"
# Deep structural analysis
leindex analyze "how authorization is enforced"
```
That's it. You're searching by meaning.
---
## What LeIndex Is Useful For
- **Understanding unfamiliar codebases** — ask questions instead of reading every file
- **Onboarding new engineers** — find relevant code without tribal knowledge
- **Exploring legacy systems** — surface logic buried in decades of code
- **AI coding assistants** — give LLMs real structural context via MCP
- **Cross-project search** — query across multiple repositories simultaneously
---
## Built for AI-Assisted Development
Modern AI coding tools struggle with large codebases because they lack global structural context.
LeIndex provides that missing layer.
It builds a semantic index of your repository that both developers and AI assistants can query to understand:
- where logic lives
- how components interact
- what code paths enforce behavior
LeIndex runs as an **MCP server**, allowing tools like **Claude Code**, **Cursor**, and other MCP-compatible agents to explore your codebase with semantic understanding.
```bash
# Start MCP stdio mode (for Claude Code / Cursor)
leindex mcp
# Or run the HTTP MCP server
leindex serve --host 127.0.0.1 --port 47268
```
```text
Claude: "Where is request validation implemented?"
LeIndex MCP → src/http/request_validator.rs
src/middleware/input_guard.rs
```
---
## How It Works
LeIndex builds a semantic index of your codebase using embeddings and structural analysis (tree-sitter parsing + program dependence graphs).
This allows queries to match:
- **code intent** — what the code does, not what it's named
- **related logic paths** — follow data flow and control flow
- **implementation patterns** — structural similarity across files
Indexes can span multiple repositories, enabling cross-project search.
```
Codebase → Tree-sitter Parser → PDG Builder → Semantic Index → Query Engine → Results
```
---
## Features
- **Semantic search** — find code by meaning, not keywords
- **PDG analysis** — program dependence graph for structural understanding
- **5-phase analysis** — additive multi-pass codebase analysis pipeline
- **Cross-project indexing** — search across multiple repos at once
- **16 MCP tools** — read, analyze, edit preview/apply, rename, impact analysis
- **HTTP + WebSocket server** — available through the unified `leindex` server modules and commands
- **Dashboard** — Bun + React operational UI with project metrics and graph telemetry
- **Low resource mode** — works on constrained hardware
- **Built in Rust** — fast indexing, low memory, safe concurrency
---
## Other Install Options
### crates.io
```bash
cargo install leindex
```
### From source
```bash
git clone https://github.com/scooter-lacroix/leindex.git
cd leindex
cargo build --release
```
**Feature flags:** Use `--features` to customize the build:
- `full` (default) — Full library plus the `leindex` CLI binary
- `minimal` — Library-focused parse/search build slice; does not produce the `leindex` binary by itself
- `cli` — Required feature for the `leindex` binary target
- `server` — Enables the HTTP/WebSocket server library modules; combine with `cli` for a runnable binary
### MCP Server Integration
LeIndex runs as an **MCP server** for AI coding tools. First install LeIndex (via crates.io or source), then configure your tool:
<details>
<summary><b>Zed IDE</b></summary>
Add to `~/.config/zed/settings.json`:
```json
{
"context_servers": {
"leindex": {
"command": {
"path": "leindex",
"args": ["mcp"]
}
}
}
}
```
</details>
<details>
<summary><b>Cursor IDE</b></summary>
Add to Cursor settings (`settings.json`):
```json
{
"mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"],
"env": {}
}
}
}
```
</details>
<details>
<summary><b>VS Code</b></summary>
Requires the [Model Context Protocol](https://marketplace.visualstudio.com/items?itemName=modelcontextprotocol.vscode-mcp) extension.
Configure in `settings.json`:
```json
{
"mcp.mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary><b>Claude Code</b></summary>
Add to `~/.config/claude-code/mcp_servers.json`:
```json
{
"mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"],
"env": {}
}
}
}
```
</details>
<details>
<summary><b>Amp CLI (Sourcegraph)</b></summary>
Add to `~/.config/amp/settings.json`:
```json
{
"amp.mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary><b>OpenCode</b></summary>
Add to `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"leindex": {
"command": ["leindex", "mcp"],
"type": "local"
}
}
}
```
</details>
<details>
<summary><b>Qwen CLI</b></summary>
Add to `~/.qwen/settings.json`:
```json
{
"mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary><b>iFlow CLI</b></summary>
Add to `~/.iflow/settings.json`:
```json
{
"mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary><b>Droid (Factory)</b></summary>
Add to `~/.factory/mcp.json` (note: requires `type: "stdio"`):
```json
{
"mcpServers": {
"leindex": {
"type": "stdio",
"command": "leindex",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary><b>Gemini CLI</b></summary>
Add to `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"leindex": {
"command": "leindex",
"args": ["mcp"]
}
}
}
```
</details>
### Dashboard (optional)
```bash
cd dashboard
bun install
bun run build
leindex dashboard
```
---
## CLI Reference
```bash
leindex index /path/to/project # Index a project
leindex search "query" # Semantic search
leindex analyze "query" # Deep structural analysis
leindex phase --all --path /path # 5-phase additive analysis
leindex diagnostics # System health check
leindex mcp # MCP stdio mode
leindex serve # HTTP/WebSocket server
leindex dashboard # Launch dashboard UI
```
---
## MCP Tools (16)
| `leindex_index` | Index a project |
| `leindex_search` | Semantic code search |
| `leindex_deep_analyze` | Deep analysis with PDG traversal |
| `leindex_context` | Expand context around a symbol |
| `leindex_phase_analysis` | 5-phase additive analysis |
| `leindex_file_summary` | Structural file analysis |
| `leindex_symbol_lookup` | Symbol definition + callers/callees |
| `leindex_project_map` | Annotated project structure |
| `leindex_grep_symbols` | Structural symbol search |
| `leindex_read_symbol` | Read symbol source with deps |
| `leindex_edit_preview` | Preview edits with impact report |
| `leindex_edit_apply` | Apply code edits |
| `leindex_rename_symbol` | Rename across all references |
| `leindex_impact_analysis` | Blast radius analysis |
| `leindex_diagnostics` | Index health and stats |
| `phase_analysis` | Alias for phase analysis |
---
## Unified Module Layout
LeIndex is now a single crate with feature-gated modules:
| `parse` | Language parsing and signature extraction |
| `graph` | Graph construction and traversal |
| `search` | Retrieval, scoring, vector search |
| `storage` | SQLite persistence + storage |
| `phase` | Additive phase analysis pipeline |
| `cli` | CLI + MCP protocol handlers |
| `global` | Cross-project discovery/registry |
| `server` | HTTP/WebSocket API server |
| `edit` | Edit preview/apply support |
| `validation` | Validation and guardrails |
Legacy crate-style aliases remain available from `leindex::leparse`, `leindex::legraphe`, and similar compatibility re-exports.
---
## Security
Database discovery (`LEINDEX_DISCOVERY_ROOTS`) is **opt-in only**. Sensitive directories (`.ssh`, `.aws`, `.gnupg`, etc.) are automatically excluded. All SQL operations use parameterized queries. See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
---
## Docs
- [ARCHITECTURE.md](ARCHITECTURE.md) — system design and internals
- [API.md](API.md) — HTTP API reference
- [docs/MCP.md](docs/MCP.md) — MCP server documentation
- [dashboard/README.md](dashboard/README.md) — dashboard setup
---
## License
MIT
