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.

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.

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

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

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

bun install
bun run build:rust
cargo test
bun run docs:build

License

MIT