Locus

Canonical package: @sylphx/locus · bin locus

Your agent searched the codebase. Did it find the right code?

Locus (repository coderag, canonical package @sylphx/locus; core library @sylphx/coderag) — local-first hybrid code search for AI assistants. One MCP call indexes your repo and returns semantic AST chunks — functions, classes, and methods — not noisy grep dumps or slow cloud pipelines.

Local-first · MCP + CLI + SDK · Hybrid TF-IDF + Vector · Rust rmcp · Evidence locators

⭐ Star this repo if agents should find code with evidence, not guess from keyword hits. · Quick start · See it work · Why not grep alone? · Product docs · Roadmap

This repository is product SSOT. Sibling agent tools live in separate repos (Citra · Iris · Cue · Spine · Lookout · Locus).

Zero-config (no install)

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

No Docker. No Chroma. No embedding API required for the default TF-IDF path.
Live: @sylphx/[email protected] · bin locus only · brand-sole serverInfo.name=locus.

Product docs

Locus vs Spine

Why Locus wins for agents

1. Right chunk, not a folder dump — AST-aware retrieval agents can patch from.
2. Zero-config — npx -y @sylphx/locus --root=… (no vector DB required by default).
3. Explainable scores — TF-IDF + matched terms, not opaque cloud ranks.
4. Local-first — code never has to leave the machine for baseline search.
5. Pairs with Spine — Locus finds code; Spine maps architecture.

The problem

Agents search codebases thousands of times per session. Most paths give you one of two bad outcomes:

1. grep/ripgrep — fast, but literal. Misses authenticateUser when you ask for "login flow". Returns whole files, not the function you need.
2. Cloud RAG — semantic, but needs Docker, vector DBs, embedding APIs, and 10–30s cold starts before the first search.

The model still guesses which snippet matters. Wrong chunk → wrong patch → wasted context.

Locus is built for the moment your agent needs the right code block, not a directory of keyword hits.

Why not grep alone?

Search latency and indexing throughput: reproduce with bun run benchmark:public-proof — do not trust hand-waved ms claims.

Full comparison: how search works.

See it work

Install once. Point at your repo.

claude mcp add locus -- npx -y @sylphx/locus --root=/absolute/path/to/project
# transitional (expand–contract still valid):

Search with the codebase_search tool:

{
  "query": "user authentication login",
  "limit": 5,
  "file_extensions": [".ts", ".tsx"],
  "exclude_paths": ["node_modules", "dist"]
}

Returns ranked chunks — not entire files:

# Search: "user authentication login" (3 results)

## src/auth/login.ts:1-12
```typescript
export async function authenticate(username: string, password: string) {
  const user = await findUserByEmail(username)
  return validatePassword(user, password)
}

## Why agents use it

| Need | What you get |
| --- | --- |
| Find implementation | AST chunks at semantic boundaries (functions, classes, methods) |
| Keyword + meaning | Hybrid TF-IDF with optional OpenAI embeddings |
| Fast iteration | Local index, incremental updates, file watching |
| Low setup | MCP server via `npx` — no Docker or ChromaDB required |
| Ship with proof | ~200 tests, reproducible public benchmark script |

## Quick Start

### Claude Code (recommended)

```bash
claude mcp add locus -- npx -y @sylphx/locus --root=/absolute/path/to/project
# transitional (expand–contract still valid):

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "coderag": {
      "command": "npx",
      "args": ["-y", "@sylphx/locus", "--root=/absolute/path/to/project"]
    }
  }
}

Any MCP Client

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

Need Cursor, VS Code, Windsurf, or library usage? See the installation guide and MCP docs.

As a Library

bun add @sylphx/coderag

import { CodebaseIndexer, PersistentStorage } from '@sylphx/coderag'

const storage = new PersistentStorage({ codebaseRoot: './my-project' })
const indexer = new CodebaseIndexer({ codebaseRoot: './my-project', storage })

await indexer.index({ watch: true })
const results = await indexer.search('authentication logic', { limit: 10 })

MCP Tool: codebase_search

Full tool reference: docs/mcp/tools.md.

Benchmark Proof

Performance claims in this README are backed only by the checked-in public benchmark script — not hand-waved marketing numbers.

bun run benchmark:public-proof

The script indexes fixtures/benchmark-corpus/ (30 TypeScript files), runs hybrid TF-IDF search 20 times (3 warmup), and prints indexing throughput plus search p50/min/max latency.

See benchmark proof for methodology and latest reproduced results.

Packages

Documentation

Security model

• Root confinement — --root pins indexing and search to one repository tree.
• Exclude paths — exclude_paths and default ignores skip node_modules, build output, and VCS metadata.
• Local-first — TF-IDF indexing runs on your machine; embeddings are optional and caller-configured.
• Evidence fields — results include file path, line range, symbol, score route, and index freshness for verification.

Example MCP request: examples/codebase-search-request.json.

Development

git clone https://github.com/SylphxAI/coderag.git
cd coderag
bun install
bun run build
bun test

Useful checks:

bun run lint
bun run typecheck
bun run docs:build
bun run benchmark:public-proof

Help this reach more builders

If wrong code snippets have wasted your agent context, your edits, or your trust in search results, you are exactly who this project is for.

⭐ Star the repo — it is the fastest way to help more agent builders find chunk-level code search. Share it in your MCP client setup, team wiki, or agent stack README.

Discovery (in progress)

Know another MCP directory? Open an issue with the link.

License

MIT © SylphxAI