Locus

Locus → 现已并入 repomap

Locus 已并入 repomap，这是面向 AI Agent 的代码库地图。它将代码图、混合搜索（Locus 的 BM25，如今基于 tree-sitter AST 分块）、调用路径、变更影响分析和交互式图形界面整合在一个 Rust 二进制文件中。它在本地运行，无需 API 密钥，并采用 MIT 许可证。

npx -y @sylphx/repomap setup

@sylphx/locus 1.x 和 @sylphx/coderag 1.x 是 @sylphx/repomap 的轻量别名，因此现有配置（npx -y @sylphx/locus --root=…、codebase_search）仍可正常使用。新开发将在 SylphxAI/repomap 中进行。本 README 其余部分介绍的是 Locus 0.x。

Locus 0.x（已归档）

精准找到任务所需的代码块

Locus 是面向编码 Agent 的本地代码搜索工具。它会为机器上的代码仓库建立索引，使用 BM25 为代码块排序，并返回路径、行范围、符号、分数和代码块文本。

无需 API 密钥。无需向量数据库。无需 Docker。默认传输方式为 stdio。

npx -y @sylphx/locus --root=/absolute/path/to/project

Locus 不会搜索进程的工作目录。请传入 --root、设置 LOCUS_ROOT，或在工具调用中传入 root。工具调用中的 root 优先级最高，其次是启动时的 --root，然后是 LOCUS_ROOT。如果未设置 LOCUS_ROOT，CODERAG_ROOT 仍然有效。

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

工具

工具	适用场景	返回内容
codebase_search	你能说出代码中出现的词	排序后的代码块。筛选条件会在应用上限前生效。
find_related	你已有一个文件和行号	与该文件共享词元的其他代码块

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

login 与 authenticate 不匹配。排序依据是词汇匹配。请搜索代码实际使用的词语。

索引内容

.ts .tsx .js .jsx .mjs .cjs .rs .md .py .go

按名称精确跳过的路径片段：node_modules、dist、target、.git。这不是 gitignore。大小超过 1,048,576 字节的文件会被跳过。新索引写入 .locus/rust-index.json 和 .locus/file-hashes.json。如果 .locus/rust-index.json 不存在，Locus 仍会读取 .coderag/。请勿提交这两个目录。

看起来像符号的行会作为代码块的起始行。其他文件则保持为一个代码块。这些模式是正则表达式，而不是语法树。符号代码块。

一如既往的默认设置

• limit 默认值为 10，必须是 1 到 100 之间的整数。
• include_content 默认值为 true。设为 false 时仅返回定位信息。
• 没有 auto、fast 或 quality 搜索模式。
• 每次调用都会刷新本地索引。未更改的文件会命中缓存。该刷新模式不是可供选择的搜索配置。
• 仅当 MCP_TRANSPORT=http 时才启用 HTTP。Agent 应使用 stdio。

安装方式

方式	位置
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	.cursor/mcp.json 或 ~/.cursor/mcp.json 中的 mcpServers
VS Code	.vscode/mcp.json 中的 servers（${workspaceFolder} 会被展开）
其他 MCP 客户端	.mcp.json 中的 mcpServers，并附带绝对路径的 --root

已发布的原生版本：@sylphx/locus-darwin-arm64、@sylphx/locus-darwin-x64、@sylphx/locus-linux-arm64-gnu、@sylphx/locus-linux-x64-gnu。Windows 不是已发布的目标平台。

npx -y @sylphx/locus doctor 会打印服务版本，以及是否找到了 locus-cli。

配套工具

产品	用途
Citra	提供 PDF 答案及页级证据
Iris	提供图像事实及像素证据
Cue	提供视频时间线及时间戳证据
Spine	展示代码库架构及影响
Lookout	提供网络研究及来源摘录

Locus 查找代码块。Spine 映射架构。只安装任务所需的工具。

文档：https://sylphxai.github.io/locus/

开发

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

许可证

MIT