Locus

io.github.SylphxAIPublished by GitHub account SylphxAIv0.6.4Updated Oct 24, 2026

Locus — the exact code chunk for the job: local BM25 search for agents.

VerifiedSTDIODesktop onlyKnowledge & Memory Developer Tools

Server details

Identifier: io.github.SylphxAI/locus
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 23, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account SylphxAI for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.SylphxAI%2Flocus.svg)](https://sourceweft.com/mcp/io.github.SylphxAI%2Flocus?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Locus is a local code search MCP server that indexes a repository and returns ranked code chunks by BM25 keyword matching for coding agents.

What you can do: Search the codebase by keyword and get ranked chunks with path, line range, symbol, score and text, with filters for file extensions, paths and exclusions before the limit applies. Find related chunks that share tokens with a given file and line. Refresh the local index on each call, with unchanged files served from cache. Return locators only when content is turned off.
When to use it: Useful when a coding assistant needs to locate the exact code chunk for a task in a local repository and you can name words that appear in the code. Ranking is lexical, so it suits keyword-style lookups rather than semantic search.
Requirements: Runs locally over stdio via the npm package, typically through npx. Needs an absolute project root passed as --root, set in LOCUS_ROOT, or given on the tool call. No API key, vector database or Docker. Published native builds cover macOS and Linux; Windows is not a published target.

Before you install

The package is now a thin alias of a successor project, and the 0.x documentation is archived. It writes index files into a .locus directory in the project, which should not be committed. It does not search the working directory, so a wrong root silently searches the wrong place. Indexing skips only a fixed set of path names, not gitignore rules.

Installation

In SourceWeft

Open Locus in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Locus → now part of repomap

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.
bash
npx -y @sylphx/repomap setup
npx -y @sylphx/repomap setup
@sylphx/locus 1.x and @sylphx/coderag 1.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 0.x (archived)

The exact code chunk for the job

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.

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:

Codex:

Tools

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

json

{  "query": "authenticate request",  "limit": 5,  "file_extensions": ["ts"],  "path_filter": "src/auth",  "exclude_paths": ["src/auth/legacy"]}

{  "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.

What is indexed

.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.

Defaults that stay boring

limit defaults to 10 and must be an integer from 1 to 100.
include_content defaults to true. false returns locators only.
There is no auto, fast, or quality search mode.
Each call refreshes the local index. Unchanged files are a cache hit. That refresh mode is not a search profile you select.
HTTP exists only when MCP_TRANSPORT=http. Agents should use stdio.

Install surfaces

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.

Companions

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/

Development

License

MIT

Source: README.md at commit 23d5eab

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v0.6.4LatestSep 23, 2026
v0.6.1Sep 23, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts