# Locus

> mind readingly accurate, blazingly fast codebase search, written in pure rust.

- **Type:** MCP server
- **Install:** `agentstack add mcp-alkinun-locus`
- **Verified:** Pending review
- **Seller:** [alkinun](https://agentstack.voostack.com/s/alkinun)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [alkinun](https://github.com/alkinun)
- **Source:** https://github.com/alkinun/locus

## Install

```sh
agentstack add mcp-alkinun-locus
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

### locus.

mind readingly accurate, blazingly fast codebase search, written in pure rust.

it is built for the kinds of fuzzy queries developers and coding agents make.

---

### install

```bash
curl -fsSL https://raw.githubusercontent.com/alkinun/locus/main/install.sh | sh
```

prebuilt release binaries are published for linux x86_64, linux arm64, and apple silicon macs.

install a specific release:

```bash
curl -fsSL https://raw.githubusercontent.com/alkinun/locus/main/install.sh | LOCUS_VERSION=v0.1.0 sh
```

from source:

```bash
cargo install --path .
```

---

### what it does

you ask locus something like:

```
where is the retry logic for failed http requests
```

```
the function that validates jwt tokens before the handler runs
```

```
error handling when the db connection drops
```

and locus finds the right parts of the codebase you are looking for.

it uses a three layer approach: lexical search (tantivy), semantic embeddings (fastembed, running locally), and a reranker. you choose how much accuracy you need versus how much latency you can tolerate.

---

### numbers

192 queries. developer questions across 11 query styles.

| mode | recall@1 | recall@5 | mrr | p50 |
|---|---|---|---|---|
| lexical only | 9.9% | 30.7% | 0.19 | 13ms |
| + embeddings | 37.5% | 75.0% | 0.53 | 34ms |
| + embeddings + reranker | **68.2%** | **89.6%** | **0.77** | 468ms |

the reranker mode is slow but powerful.

full eval breakdown in [evals.md](./evals.md).

---

### usage

```bash
# build the local index first
locus index --path /path/to/repo

# first run, if the embedding model is not already cached
locus index --path /path/to/repo --download-embedding

# interactive terminal ui
locus --path /path/to/repo

# lexical search. instant, good for known symbol names
locus search "AuthMiddleware" --no-embedding

# semantic search. default, much better fuzzy recall
locus search "where does the session get invalidated"

# reranker. best recall, worth the wait for agents and scripts
locus search "retry logic for failed http requests" --rerank

# json output. pipe to anything
locus search "database connection pooling" --format json | jq '.[].file_path'

# grouped output. split primary code, supporting types, tests, docs, and config
locus search "tests for chunking" --grouped --format json

# search a specific directory
locus search "error handling in the parser" --path /path/to/repo

# run as a stdio mcp server for coding agents
locus mcp --path /path/to/repo
```

### vs code extension

A lightweight VS Code extension is available in [`vscode-extension`](./vscode-extension). It uses the same `locus` binary for indexing, search, the terminal UI, MCP, eval generation, and eval runs; search results open directly at the matching source lines.

```bash
cd vscode-extension
npm install
npm run compile
```

---

### mcp server

`locus mcp` starts a stdio mcp server that a coding agent can use to search the repo it is working in. configure the agent to launch:

```bash
locus mcp --path /path/to/repo
```

it exposes three tools:

- `search_codebase`: search indexed code chunks by natural language or symbol.
- `index_codebase`: build or rebuild `.locus/index` for the repo.
- `index_status`: check whether the repo has a usable locus index.

the mcp server writes protocol messages only to stdout. indexing progress and diagnostics go to stderr.

---

### how it works

locus indexes your codebase using treesitter to parse code into semantically meaningful chunks. it understands function boundaries, class definitions, impls, structs, enums, traits, tests, and modules in rust, python, javascript, typescript, go, java, c, c++, c#, ruby, and swift. it also indexes markdown headings and small config files.

at query time it combines:

- **bm25** (tantivy) for exact and near-exact matches
- **local embeddings** (fastembed, runs entirely on your machine) for semantic similarity
- **an optional cross-encoder reranker** to re-score the top candidates

no data leaves your machine during indexing or search. the index lives next to your code in `.locus/index`.

---

### supported languages

rust · python · javascript · typescript · go · java · c · c++ · c# · ruby · swift · markdown · config

more coming.

---

### license

licensed under either of:

- mit ([LICENSE-MIT](LICENSE-MIT))
- apache 2.0 ([LICENSE-APACHE](LICENSE-APACHE))

at your option.

---

### philosophy

one thing done well. locus is a search tool. it does not generate code, summarize files, or try to be an agent itself. it answers "where is this" with high accuracy and low noise.

---

### contributing

issues and prs are very welcome.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [alkinun](https://github.com/alkinun)
- **Source:** [alkinun/locus](https://github.com/alkinun/locus)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-alkinun-locus
- Seller: https://agentstack.voostack.com/s/alkinun
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.