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.

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

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

Full comparison: how search works.

Install once. Point at your repo.

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

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 coderag -- npx @sylphx/coderag-mcp --root=/absolute/path/to/project

Add to claude_desktop_config.json:

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

npx @sylphx/coderag-mcp --root=/absolute/path/to/project

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

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 })

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

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.

• 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.

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

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.

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

MIT © SylphxAI