Free, Open Source, Local / Offline Capable, Container-Free Semantic Search For Your Codebase
VibeRAG is fully local, offline capable MCP server for local codebase search.
VibeRAG automatically indexes your codebase into a local container-free vector database (lancedb). Every time you make a change, the indexes are automatically updated.
npm install -g viberag
# Initialize in your project
cd your-project
viberag
# Run the initialization wizard to configure embeddings, run initial indexing, and automatically configure MCP server integration.
/init
# In addition to allowing Agents to search via the MCP server,
# you can search yourself via the CLI.
/search authentication handler
When using a coding agent like Claude Code, add use viberag to your prompt.
────────────────────────────────────────────────────────────────────
> How is authentication handled in this repo? use viberag
────────────────────────────────────────────────────────────────────
Tip: include "
use viberag" in your prompt to ensure your agent will use viberag's codebase search features. Most agents will select MCP tools as appropriate, but sometimes they need a little help with explicit prompting.
.gitignore + .viberagignore) and reindexes only what has changed in real time/cancel and clear status reporting via /statusYour coding agent would normally use Search / Grep / Find and guess search terms that are relevant. VibeRAG indexes the codebase into a local vector database (based on lancedb) and can use semantic search to find all relevant code snippets even if the search terms are not exact.
When searching for "authentication", VibeRAG will find all code snippets that are relevant to authentication, such as "login", "logout", "register", and names of functions and classes like AuthDependency, APIKeyCache, etc.
This ensures comprehensive search of your codebase so you don't miss important files and features that are relevant to your changes or refactor.
Semantic search is especially useful in monorepos, where you may be trying to understand how different parts of the codebase interact with each other. Viberag can find all the pieces with fewer searches, fewer tokens used, and a shorter amount of time spent searching.
All options store embeddings and indexed data on your local machine
Local: You can use a locally run embedding model (Qwen3-Embedding-0.6B) so that nothing leaves your machine. This has a smaller vocabulary and is only recommended for privacy and offline concerns.
Recommended: API generated embeddings from Gemini, OpenAI, and Mistral are recommended for the largest vocabulary and highest quality semantic meaning.
VibeRAG includes an MCP server that integrates with AI coding tools.
Run /mcp-setup in the VibeRAG CLI for interactive setup. This wizard will attempt to automatically configure your coding agents / editors with viberags MCP server settings.
# Start viberag
$ viberag
# Run the setup wizard (after having initialized with /init)
$ /mcp-setup
# Automatic configuration wizard
╭───────────────────────────────────────────────────────────────╮
│ MCP Setup Wizard │
│ │
│ Select AI coding tool(s) to configure: │
│ (Space to toggle, Enter to confirm) │
│ │
│ > [x] Claude Code (auto-setup) │
│ [ ] Cursor (auto-setup) │
│ [ ] Gemini CLI (global config) │
│ [ ] JetBrains IDEs (manual setup) │
│ [ ] OpenAI Codex (global config) │
│ [ ] OpenCode (global config) │
│ [ ] Roo Code (auto-setup) │
│ [ ] VS Code Copilot (auto-setup) │
│ [ ] Windsurf (global config) │
│ [ ] Zed (global config) │
│ │
│ 1 selected | ↑/↓ move, Space toggle, Enter confirm, Esc cancel│
╰───────────────────────────────────────────────────────────────╯
The wizard can auto-configure project-level configs and merge into global configs.
The following sections describe manual MCP server setup configurations for various editors and agents.
CLI Command:
claude mcp add viberag -- npx viberag-mcp
Tool Search: Claude Code supports MCP Tool Search (beta) to discover MCP tools on-demand when many tools are installed. It is enabled by default; to force-enable set
ENABLE_TOOL_SEARCH=truewhen launchingclaude.
Global Config: ~/.claude.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Project Config: .mcp.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Verify: Run /mcp in Claude Code, look for "viberag: connected"
Global Config: ~/.cursor/mcp.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Project Config: .cursor/mcp.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Verify: Settings → Cursor Settings → MCP, verify "viberag" shows with toggle enabled
CLI Command:
gemini mcp add viberag -- npx viberag-mcp
Global Config: ~/.gemini/settings.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Project Config: .gemini/settings.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Verify: Run /mcp in Gemini CLI, look for "viberag" in server list
UI Setup:
viberagnpxviberag-mcpVerify: Settings → Tools → AI Assistant → MCP, verify "viberag" shows green in Status column
CLI Command:
codex mcp add viberag -- npx -y viberag-mcp
Global Config: ~/.codex/config.toml
[mcp_servers.viberag]
command = "npx"
args = ["-y", "viberag-mcp"]
Note: The
-yflag is required for npx to auto-confirm package installation
Verify: Run /mcp in Codex TUI, look for "viberag" in server list
Global Config: ~/.config/opencode/opencode.json (Linux/macOS) or %APPDATA%/opencode/opencode.json (Windows)
{
"mcp": {
"viberag": {
"type": "local",
"command": ["npx", "-y", "viberag-mcp"]
}
}
}
Project Config: opencode.json
{
"mcp": {
"viberag": {
"type": "local",
"command": ["npx", "-y", "viberag-mcp"]
}
}
}
Note: OpenCode uses
"mcp"key and requires"type": "local"with command as an array
Verify: Check MCP servers list in OpenCode, verify "viberag" appears and is enabled
Global Config: UI only — Click MCP icon in Roo Code pane header → Edit Global MCP
Project Config: .roo/mcp.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Verify: Click MCP icon in Roo Code pane header, verify "viberag" appears in server list
Global Config: Add to User settings.json under mcp.servers:
{
"mcp": {
"servers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
}
Project Config: .vscode/mcp.json
{
"servers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Note: VS Code uses
"servers"instead of"mcpServers"
Required: Enable Agent Mode in VS Code settings:
- Settings → search
chat.agent.enabled→ check the box, OR- Add
"chat.agent.enabled": trueto your Usersettings.json
Verify: Cmd/Ctrl+Shift+P → "MCP: List Servers", verify "viberag" appears
Global Config: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"viberag": {
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Verify: Click Plugins icon in Cascade panel, verify "viberag" shows in plugin list
Global Config: ~/.config/zed/settings.json
{
"context_servers": {
"viberag": {
"source": "custom",
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Project Config: .zed/settings.json
{
"context_servers": {
"viberag": {
"source": "custom",
"command": "npx",
"args": ["viberag-mcp"]
}
}
}
Note: Zed uses
"context_servers"instead of"mcpServers"and requires"source": "custom"for non-extension servers
Verify: Open Agent Panel settings, verify "viberag" shows green indicator
VibeRAG exposes a small set of agent-centric tools. Backward compatibility with legacy tool names is not provided.
| Tool | Description |
|---|---|
codebase_search | Intent-routed search with grouped results + stable IDs for follow-ups |
help | Usage guide for MCP tools + how search works |
read_file_lines | Read an exact line range from disk |
get_symbol_details | Fetch a symbol definition + deterministic metadata by symbol_id |
find_references | Find usage occurrences (refs) for a symbol name or symbol_id |
get_surrounding_code | Expand a hit into neighbors (symbols/chunks) and related metadata |
build_index | Build/update the index (incremental by default) |
get_status | Get index + daemon status summary |
get_watcher_status | Get watcher status (auto-indexing) |
cancel_operation | Cancel indexing or warmup without shutting down the daemon |
codebase_searchSingle entry point with intent routing. Use scope for transparent filters.
intent: auto|definition|usage|concept|exact_text|similar_codescope: path_prefix, path_contains, path_not_contains, extensionexplain: include per-hit channels + ranking priorsExample:
{
"query": "how does authentication work",
"intent": "concept",
"scope": {
"path_prefix": ["src/"],
"path_not_contains": ["test", "__tests__", ".spec.", ".test."]
},
"k": 20,
"explain": true
}
Follow-ups: get_symbol_details, read_file_lines, get_surrounding_code, find_references.
VibeRAG includes a CLI for easy execution of initialization, indexing, setup, and other things you may want to manually control outside of agent use.
| Command | Description |
|---|---|
/init | Initialize VibeRAG (configure embeddings, index codebase) |
/index | Index the codebase (incremental) |
/reindex | Force full reindex |
/search <query> | Semantic search |
/status | Show daemon and index status |
/cancel | Cancel indexing or warmup |
/mcp-setup | Configure MCP server for AI tools |
/clean | Remove VibeRAG from project |
/help | Show all commands |
VibeRAG stores all per-project state (config, index, logs) globally under:
~/.local/share/viberag/projects/<projectId>/ (override via VIBERAG_HOME)No files are written into your repo.
VibeRAG uses .gitignore rules to exclude files and folders from indexing. For
non-git projects (or for additional ignore patterns), you can create a
.viberagignore file in the project root.
.viberagignore uses the exact same pattern syntax as .gitignore.gitignore (if present)Example .viberagignore:
# build outputs
dist/
build/
# local artifacts
coverage/
tmp/
# generated bundles
**/*.min.js
VibeRAG writes per-service logs with hourly rotation:
~/.local/share/viberag/projects/<projectId>/logs/daemon/ - daemon lifecycle and IPC errors~/.local/share/viberag/projects/<projectId>/logs/indexer/ - indexing progress, retries, and batch failures~/.local/share/viberag/projects/<projectId>/logs/mcp/ - MCP server errors~/.local/share/viberag/projects/<projectId>/logs/cli/ - CLI errorsIf indexing appears slow or retries are happening, check the latest file under
~/.local/share/viberag/projects/<projectId>/logs/indexer/.
Choose your embedding provider during /init:
| Model | Quant | Download | RAM |
|---|---|---|---|
| Qwen3-0.6B | Q8 | ~700MB | ~1.5GB |
| Provider | Model | Dims | Cost | Get API Key |
|---|---|---|---|---|
| Gemini | gemini-embedding-001 | 1536 | Free tier | Google AI Studio |
| Mistral | codestral-embed | 1536 | $0.10/1M | Mistral Console |
| OpenAI | text-embedding-3-large | 1536 | $0.13/1M | OpenAI Platform |
API keys are entered during the /init wizard and stored globally in ~/.local/share/viberag/secrets/secrets.json (override via VIBERAG_HOME). Project configs store only a key id reference (never the raw API key).
VibeRAG works best when AI agents use sub-agents for exploration tasks. This keeps the main conversation context clean and uses ~8x fewer tokens.
When an AI calls viberag directly, all search results expand the main context. Sub-agents run searches in isolated context windows and return only concise summaries.
| Approach | Context Usage | Token Efficiency |
|---|---|---|
| Direct viberag calls | 24k tokens | Baseline |
| Sub-agent delegation | 3k tokens | 8x better |
# For exploration tasks, use the Task tool:
Task(subagent_type='Explore', prompt='Use viberag to find how authentication works')
# For parallel comprehensive search:
Task(subagent_type='Explore', prompt='Search auth patterns') # runs in parallel
Task(subagent_type='Explore', prompt='Search login flows') # with this one
Add to your CLAUDE.md:
When exploring the codebase, use Task(subagent_type='Explore') and instruct it
to use the viberag `codebase_search` tool (and follow-ups like `get_symbol_details` / `read_file_lines`). This keeps the main context clean.
/delegate to hand off exploration tasks to Copilot coding agentgemini mcp add viberag then reference in extension configsauto_approve in settings for autonomous agent operation| Task Type | Recommended Approach |
|---|---|
| "Where is function X defined?" | codebase_search with intent="definition" |
| "What file handles Y?" | codebase_search with intent="concept" (check files) |
| "How does authentication work?" | Sub-agent - needs multi-step search + follow-ups |
| "Find all API endpoints" | Sub-agent - iterative search + scope filters |
| "Understand the data flow" | Sub-agent - iterative exploration |
Use a few targeted codebase_search calls with different intents, then follow up with
get_symbol_details, read_file_lines, get_surrounding_code, and find_references as needed.
Example sequence:
{"query": "authentication", "intent": "concept", "k": 20}
{
"query": "login",
"intent": "definition",
"k": 20,
"scope": {"path_prefix": ["src/"]}
}
{"symbol_name": "login", "k": 200}
Large repos can exceed OS watch limits. The watcher honors .gitignore and .viberagignore, but if you still see EMFILE:
.gitignore or .viberagignore to reduce watched files.kern.maxfiles, kern.maxfilesperproc, and ulimit -nfs.inotify.max_user_watches, fs.inotify.max_user_instances, and ulimit -nIf indexing fails due to transient network/API issues:
/status to confirm daemon/index state./index after connectivity is stable./cancel to stop a stuck run, then /reindex if you need a clean rebuild.FAQs
Local code RAG for AI coding assistants - semantic search via MCP server
We found that viberag demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.