Locus

The exact code chunk for the job

Locus gives coding agents fast, local code search that returns complete,
implementation-ready chunks instead of grep dumps or whole-file guesses.

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

For Claude Code:

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

The fastest useful workflow

Ask a natural-language question:

{
  "query": "where is user authentication enforced?",
  "limit": 5
}

Locus returns ranked AST chunks with file paths, line ranges, symbol names,
score explanations, freshness, and explicit gaps.

Jobs Locus is built for

Ask your agent	Locus returns
“Where is this behavior implemented?”	`codebase_search`
“What code is related to this function?”	`find_related`
“Search across these repositories.”	cross-repo search
“Find the implementation, not tests or declarations.”	ranked code chunks
“Give me enough context to edit safely.”	compact, deduplicated results

Tool surface

Tool	Purpose
`codebase_search`	Hybrid local search over code chunks
`find_related`	Find related chunks from a known file and line

The public surface stays small. Indexing is cached locally and refreshed when
the repository changes. Optional embeddings are opt-in and never required for
the default path.

Predictable defaults

Locus does not hide expensive work behind “auto”.

fast is the default local TF-IDF and AST path.
quality enables optional vectors and reranking when configured.
research is not a Locus mode; use a separate web tool for external sources.
No Docker, vector database, or API key is required.
Generated files, dependencies, and build output are excluded by default.

Why agents use it

AST boundaries return functions, classes, and methods.
Hybrid ranking combines lexical and semantic evidence when available.
Results include score components instead of opaque ordering.
Token budgets and dedup keep context small.
Local indexes keep code on the machine.

Companion MCP tools

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 code chunk; Spine maps the repository architecture. Each product
is independent, so install only the tools your agent needs.

Development

bun install
bun run build
bun test
cargo test
bun run benchmark:public-proof
bun run benchmark:release-gate

License

MIT