Coderag

---

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.

Setup	Command
Zero-config MCP	npx -y @sylphx/locus --root=/abs/path
Claude Code	claude mcp add locus -- npx -y @sylphx/locus --root=/abs/path
Cursor / Desktop	"command":"npx","args":["-y","@sylphx/locus","--root=/abs/path"]

Product docs

Doc	Purpose
docs/POSITIONING.md	Strategic positioning (Locus vs Spine)
docs/COMPETITIVE.md	Peer anchors and wedge
docs/EVIDENCE_CONTRACT.md	Evidence = result contract (not a tool name)
docs/TOOL_SURFACE.md	Few clear tools policy
docs/LOCAL_FIRST_FRONTIER.md	Local-first / zero-config / Rust-first
docs/PRODUCT_INDEPENDENCE.md	This repo is SSOT
docs/BRAND_PUBLISH.md	Brand-sole npm ids
docs/IPPB.md	Independent public product bar
docs/PUBLISH.md	npm/git publish status

Locus vs Spine

	Locus	Spine
Job	Find the right code chunk	Map architecture (path / trace / impact)
Repo	coderag	architecture-reader-mcp
Primary tool	codebase_search	architecture_*
Brand npm	@sylphx/locus	@sylphx/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?

	grep/ripgrep	Cloud RAG	Locus
Semantic understanding	❌ Literal match	✅ Embeddings	✅ TF-IDF + optional vectors
Zero external deps	✅	❌ Vector DB + embed API	✅ Local by default
Offline support	✅	❌	✅
Result shape	Whole files / lines	Often whole files	AST chunks (functions, classes)
Agent setup	Shell tool	Docker + services	npx -y @sylphx/locus

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

Parameter	Type	Default	Description
query	string	—	Search query (required)
limit	number	10	Max results
include_content	boolean	true	Include code snippets
file_extensions	string[]	—	Filter by extension
path_filter	string	—	Filter by path pattern
exclude_paths	string[]	—	Exclude paths

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

Package	Description	Install
@sylphx/coderag	Core search library	npm i @sylphx/coderag
@sylphx/locus	MCP server for AI assistants	npx -y @sylphx/locus

---

Documentation

Topic	Link
Docs site	coderag.sylphx.com
Getting started	docs/guide/getting-started.md
MCP server	docs/mcp/overview.md
How search works	docs/guide/how-search-works.md
Benchmark proof	docs/benchmark.md
Stop code-search guessing	docs/articles/stop-code-search-guessing.md
API reference	docs/api/overview.md

---

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)

Channel	Status
Official MCP Registry	Not listed yet — no server.json publish workflow in this repo
Glama MCP directory	Not listed yet
mcpservers.org submit	Not listed yet — free web-form submission
mcp.so	Not listed yet

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

---

License

MIT © SylphxAI