Coderag

CodeRAG

Lightning-fast hybrid code search for AI assistants

[](https://www.npmjs.com/package/@sylphx/coderag) [](https://www.npmjs.com/package/@sylphx/coderag-mcp) [](https://github.com/SylphxAI/coderag/actions) [](LICENSE)

Zero dependencies • **

---

Why CodeRAG?

Traditional code search tools are either slow (full-text grep), inaccurate (keyword matching), or complex (require external services).

CodeRAG is different:

❌ Old way: Docker + ChromaDB + Ollama + 30 second startup
✅ CodeRAG: npx @sylphx/coderag-mcp (instant)

| Feature | grep/ripgrep | Cloud RAG | CodeRAG | |---------|-------------|-----------|---------| | Semantic understanding | ❌ | ✅ | ✅ | | Zero external deps | ✅ | ❌ | ✅ | | Offline support | ✅ | ❌ | ✅ | | Startup time | Instant | 10-30s | {

## src/utils/large.ts:1-200 [truncated]
```typescript
1: // First 70% shown...

... [800 chars truncated] ...

195: // Last 20% shown

---

## 📚 API Reference

### `CodebaseIndexer`

Main class for indexing and searching.

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

const storage = new PersistentStorage({ codebaseRoot: './project' })
const indexer = new CodebaseIndexer({
  codebaseRoot: './project',
  storage,
  maxFileSize: 1024 * 1024, // 1MB default
})

// Index with file watching
await indexer.index({ watch: true })

// Search with options
const results = await indexer.search('query', {
  limit: 10,
  includeContent: true,
  fileExtensions: ['.ts', '.js'],
  excludePaths: ['node_modules'],
})

// Stop watching
await indexer.stopWatch()

PersistentStorage

SQLite-backed storage for instant startup.

import { PersistentStorage } from '@sylphx/coderag'

const storage = new PersistentStorage({
  codebaseRoot: './project',  // Creates .coderag/ folder
  dbPath: './custom.db',      // Optional custom path
})

Low-Level TF-IDF Functions

import { buildSearchIndex, searchDocuments, initializeTokenizer } from '@sylphx/coderag'

// Initialize StarCoder2 tokenizer (4.7MB, one-time download)
await initializeTokenizer()

// Build index
const documents = [
  { uri: 'file://auth.ts', content: 'export function authenticate...' },
  { uri: 'file://user.ts', content: 'export class User...' },
]
const index = await buildSearchIndex(documents)

// Search
const results = await searchDocuments('authenticate user', index, { limit: 5 })

Vector Search (Optional)

For semantic search with embeddings:

import { hybridSearch, createEmbeddingProvider } from '@sylphx/coderag'

// Requires OPENAI_API_KEY environment variable
const results = await hybridSearch('authentication flow', indexer, {
  vectorWeight: 0.7,  // 70% vector, 30% TF-IDF
  limit: 10,
})

---

⚙️ Configuration

MCP Server Options

| Option | Default | Description | |--------|---------|-------------| | --root= | Current directory | Codebase root path | | --max-size= | 1048576 (1MB) | Max file size to index | | --no-auto-index | false | Disable auto-indexing on startup |

Environment Variables

| Variable | Description | |----------|-------------| | OPENAI_API_KEY | Enable vector search with OpenAI embeddings | | OPENAI_BASE_URL | Custom OpenAI-compatible endpoint | | EMBEDDING_MODEL | Embedding model (default: text-embedding-3-small) | | EMBEDDING_DIMENSIONS | Custom embedding dimensions |

---

📊 Performance

| Metric | Value | |--------|-------| | Initial indexing | ~1000-2000 files/sec | | Startup with cache | /` tags in HTML.

---

🔧 Development

# Clone
git clone https://github.com/SylphxAI/coderag.git
cd coderag

# Install
bun install

# Build
bun run build

# Test
bun run test

# Lint & Format
bun run lint
bun run format

---

🤝 Contributing

Contributions are welcome! Please:

1. Open an issue to discuss changes
2. Fork and create a feature branch
3. Run bun run lint and bun run test
4. Submit a pull request

---

📄 License

MIT © Sylphx

---

Powered by Sylphx

Built with @sylphx/synth • @sylphx/mcp-server-sdk • @sylphx/bump

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SylphxAI
• Source: SylphxAI/coderag
• License: MIT
• Homepage: https://sylphx.com

Install and usage instructions live in the source repository linked above.