Deprecated. Deprecated by the publisher: Merged into repomap. Use io.github.SylphxAI/repomap (npm @sylphx/repomap).
Locus — the exact code chunk for the job: local BM25 search for agents.
Runs on your machine from its package; the steps are below.
At most: only reads or looks up information.
Odel charges nothing per call. The publisher may charge for its own service.
Runs locally over stdio
This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).
Run
npx -y @sylphx/locus
MCP client config
{
"mcpServers": {
"locus": {
"command": "npx",
"args": [
"-y",
"@sylphx/locus"
]
}
}
}Locus has merged into repomap, a map of your codebase for AI agents. It combines code graph, hybrid search (Locus's BM25, now on tree-sitter AST chunks), call paths, change impact and an interactive graph UI in one Rust binary. It runs locally, needs no API key, and is MIT licensed.
bashnpx -y @sylphx/repomap setup
@sylphx/locus1.x and@sylphx/coderag1.x are thin aliases of@sylphx/repomap, so existing configs (npx -y @sylphx/locus --root=…,codebase_search) keep working. New development happens in SylphxAI/repomap. The rest of this README documents Locus 0.x.
Locus is local code search for coding agents. It indexes the repository on the machine, ranks chunks with BM25, and returns the path, line range, symbol, score, and chunk text.
No API key. No vector database. No Docker. The default transport is stdio.
npx -y @sylphx/locus --root=/absolute/path/to/project
Locus does not search the process working directory. Pass --root, set LOCUS_ROOT, or pass root on the tool call. A tool root wins, then the launch --root, then LOCUS_ROOT. CODERAG_ROOT still works when LOCUS_ROOT is unset.
Claude Code:
claude mcp add locus -- npx -y @sylphx/locus --root=/absolute/path/to/project
Codex:
codex mcp add locus -- npx -y @sylphx/locus --root=/absolute/path/to/project
| Tool | Use it when | You get |
|---|---|---|
codebase_search | You can name words that appear in the code | Ranked chunks. Filters apply before the limit. |
find_related | You already have a file and a line | Other chunks that share its tokens |
{
"query": "authenticate request",
"limit": 5,
"file_extensions": ["ts"],
"path_filter": "src/auth",
"exclude_paths": ["src/auth/legacy"]
}
login does not match authenticate. Ranking is lexical. Search for the words the code uses.
.ts .tsx .js .jsx .mjs .cjs .rs .md .py .go
Skipped path segments, by exact name: node_modules, dist, target, .git. This is not gitignore. Files larger than 1,048,576 bytes are skipped. New indexes are written to .locus/rust-index.json and .locus/file-hashes.json. Locus still reads .coderag/ when .locus/rust-index.json is absent. Do not commit either directory.
A line that looks like a symbol starts a chunk. Other files stay one chunk. The patterns are regular expressions, not a syntax tree. Symbol chunks.
limit defaults to 10 and must be an integer from 1 to 100.include_content defaults to true. false returns locators only.auto, fast, or quality search mode.MCP_TRANSPORT=http. Agents should use stdio.| Surface | Where |
|---|---|
| Claude Code | claude mcp add locus -- npx -y @sylphx/locus --root=/absolute/path/to/project |
| Codex | codex mcp add locus -- npx -y @sylphx/locus --root=/absolute/path/to/project |
| Cursor | mcpServers in .cursor/mcp.json or ~/.cursor/mcp.json |
| VS Code | servers in .vscode/mcp.json (${workspaceFolder} is expanded) |
| Other MCP clients | mcpServers in .mcp.json, with an absolute --root |
Published natives: @sylphx/locus-darwin-arm64, @sylphx/locus-darwin-x64, @sylphx/locus-linux-arm64-gnu, @sylphx/locus-linux-x64-gnu. Windows is not a published target.
npx -y @sylphx/locus doctor prints the server version and whether locus-cli was found.
| Product | Job |
|---|---|
| Citra | PDF answers with page-level proof |
| Iris | Image facts and pixel evidence |
| Cue | Video timelines and timestamp evidence |
| Spine | Repository architecture and impact |
| Lookout | Web research with source excerpts |
Locus finds the chunk. Spine maps the architecture. Install only what the task needs.
Docs: https://sylphxai.github.io/locus/
bun install
bun run build:rust
cargo test
bun run docs:build
MIT