dolphin

🐬 Dolphin

Hybrid search across all your repositories.

---

Dolphin indexes your repositories and lets you perform hybrid (semantic + keyword) search across them.

Quickstart

# Install
uv pip install pb-dolphin

# Set your OpenAI key (used for embeddings)
export OPENAI_API_KEY="sk-..."

# Initialize, add a repo, and search
dolphin init
dolphin add-repo my-project /path/to/project
dolphin index my-project
dolphin search "database connection pooling"

Dolphin indexes your code with language-aware chunking, embeds it, and returns ranked results.

Want live re-indexing as you edit files? Start the server:

dolphin serve

Agent Integration

A small companion MCP server is available at bunx dolphin-mcp. Add this to your AI app's MCP config:

{
  "mcpServers": {
    "dolphin": {
      "command": "bunx",
      "args": ["dolphin-mcp"]
    }
  }
}

Make sure dolphin serve is running, and your agent can now search, retrieve chunks, and read files from your indexed repos.

Additionally, a Claude skill is available in this repo's marketplace as a personal Plugin.

How it works

  You / Agent
        |
        v
  ┌───────────────────────────────────────┐
  │             Dolphin                   │
  │                                       │
  │   CLI ─── REST API ─── MCP Bridge     │
  │               |                       │
  │        ┌──────┴──────┐                │
  │        v             v                │
  │    LanceDB       SQLite               │
  │   (vectors)    (metadata + BM25)      │
  └───────────────────────────────────────┘

Indexing: Your code is scanned, split into semantic chunks using language-aware AST parsers, embedded via OpenAI, and stored in LanceDB (vectors) and SQLite (metadata + full-text).

Searching: Your query is embedded and matched against both vector similarity and BM25 keyword relevance. Results are fused with Reciprocal Rank Fusion, optionally reranked with a cross-encoder, and returned as structured snippets with file paths, line numbers, and scores.

Features

Intelligent hybrid search

• Hybrid vector + BM25 keyword search with RRF fusion
• Optional cross-encoder reranking for +20-30% ranking improvement
• MMR diversity to reduce redundant results
• Filter by repo, language, path, or glob pattern

Language-aware indexing

• AST-based chunking for Python, TypeScript, JavaScript, Markdown, SQL, and Svelte
• Fallback text chunking for everything else
• Respects .gitignore and an optional repo-specific Dolphin config (dolphin init --repo)

Live sync

• File-watching built into dolphin serve so edits are re-indexed automatically
• Git-aware: handles branch switches gracefully

Multiple interfaces

• dolphin CLI with compact, verbose, and JSON output modes
• FastAPI server with full search and retrieval endpoints
• MCP server for integration via bunx dolphin-mcp

Supported chunking languages

Dolphin uses language-aware AST chunkers for the best possible search quality. Files in other recognized languages fall back to token-window chunking, and completely unknown extensions use a generic text chunker.

Language	Extensions	Chunker
Python	.py, .pyw, .pyi	AST
TypeScript	.ts, .tsx	AST
JavaScript	.js, .jsx, .mjs, .cjs	AST
Markdown	.md, .markdown	AST
SQL	.sql	AST
Svelte	.svelte	AST
Go, Rust, Java, C/C++	.go, .rs, .java, .c, .cpp	Token-window
Ruby, PHP, C#, Swift, Kotlin	.rb, .php, .cs, .swift, .kt	Token-window
Shell	.sh, .bash, .zsh	Token-window
Config (JSON, YAML, TOML, XML)	.json, .yaml, .yml, .toml, .xml	Token-window

You can customize extension mappings in ~/.dolphin/config.toml under the [languages] section.

CLI reference