Locus

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

@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

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

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

Locus finds the chunk. Spine maps the architecture. Install only what the task needs.

Docs: https://sylphxai.github.io/locus/

Development

bun installbun run build:rustcargo testbun run docs:build

License

MIT