viberag 0.1.5 → 0.1.7

package/README.md

@@ -1,10 +1,10 @@
 ![VibeRAG Banner](https://github.com/mdrideout/viberag/blob/master/viberag-banner-opt.png?raw=true)
 
-# VIBERAG
+# VIBERAG MCP Server
 
 **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 is fully local, offline capable MCP server for local codebase search.
 
 - Semantic codebase search
 - Keyword codebase search (BM25)
@@ -28,7 +28,7 @@ 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, 
+# In addition to allowing Agents to search via the MCP server,
 # you can search yourself via the CLI.
 /search authentication handler
 ```
@@ -45,18 +45,18 @@ When using a coding agent like [Claude Code](https://claude.ai/code), add `use v
 
 > **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.
 
-
 ## Features
 
 - **CLI based setup** - CLI commands and wizards for setup, editor integration, and configuration
 - **Semantic code search** - Find code by meaning, not just keywords
 - **Flexible embeddings** - Local model (offline, free) or cloud providers (Gemini, Mistral, OpenAI)
 - **MCP server** - Works with Claude Code, Cursor, VS Code Copilot, and more
-- **Incremental indexing** - Only re-embeds changed files
+- **Automatic Incremental indexing** - Watches for file changes and reindexes only what has changed in real time
 - **Multi-language support** - TypeScript, JavaScript, Python, Go, Rust, and more
 
 ### How It Works:
-Your 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](https://lancedb.com/)) and can use semantic search to find all relevant code snippets even if the search terms are not exact. 
+
+Your 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](https://lancedb.com/)) 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.
 
@@ -67,16 +67,16 @@ This ensures a more exhaustive search of your codebase so you don't miss importa
 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.
 
 ### Embedding Models
-- You can use a locally run embedding model ([Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B)) so that nothing leaves your machine. 
 
-- SOTA API based embeddings from [Gemini](https://ai.google.dev/gemini-api/docs/embeddings), [OpenAI](https://platform.openai.com/docs/guides/embeddings), and [Mistral](https://docs.mistral.ai/capabilities/embeddings) are also supported.
+- You can use a locally run embedding model ([Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B)) so that nothing leaves your machine.
 
+- SOTA API based embeddings from [Gemini](https://ai.google.dev/gemini-api/docs/embeddings), [OpenAI](https://platform.openai.com/docs/guides/embeddings), and [Mistral](https://docs.mistral.ai/capabilities/embeddings) are also supported.
 
-## MCP Server Setup
+## MCP Server
 
 VibeRAG includes an MCP server that integrates with AI coding tools.
 
-### Setup Wizard
+### IDE / Agent Setup Wizard
 
 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.
 
@@ -125,19 +125,21 @@ These editors use per-project config files that VibeRAG can auto-create.
 <summary><strong>Claude Code</strong> — <code>.mcp.json</code></summary>
 
 **CLI Command:**
+
 ```bash
 claude mcp add viberag -- npx viberag-mcp
 ```
 
 **Manual Setup:**
+
 ```json
 {
-  "mcpServers": {
-    "viberag": {
-      "command": "npx",
-      "args": ["viberag-mcp"]
-    }
-  }
+	"mcpServers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -151,14 +153,15 @@ claude mcp add viberag -- npx viberag-mcp
 <summary><strong>Cursor</strong> — <code>.cursor/mcp.json</code></summary>
 
 **Manual Setup:**
+
 ```json
 {
-  "mcpServers": {
-    "viberag": {
-      "command": "npx",
-      "args": ["viberag-mcp"]
-    }
-  }
+	"mcpServers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -172,14 +175,15 @@ claude mcp add viberag -- npx viberag-mcp
 <summary><strong>Roo Code</strong> — <code>.roo/mcp.json</code></summary>
 
 **Manual Setup:**
+
 ```json
 {
-  "mcpServers": {
-    "viberag": {
-      "command": "npx",
-      "args": ["viberag-mcp"]
-    }
-  }
+	"mcpServers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -193,14 +197,15 @@ claude mcp add viberag -- npx viberag-mcp
 <summary><strong>VS Code Copilot</strong> — <code>.vscode/mcp.json</code></summary>
 
 **Manual Setup:**
+
 ```json
 {
-  "servers": {
-    "viberag": {
-      "command": "npx",
-      "args": ["viberag-mcp"]
-    }
-  }
+	"servers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -222,19 +227,21 @@ These editors use global config files. VibeRAG can merge into existing configs.
 <summary><strong>Gemini CLI</strong> — <code>~/.gemini/settings.json</code></summary>
 
 **CLI Command:**
+
 ```bash
 gemini mcp add viberag -- npx viberag-mcp
 ```
 
 **Manual Setup:** Add to your existing settings.json:
+
 ```json
 {
-  "mcpServers": {
-    "viberag": {
-      "command": "npx",
-      "args": ["viberag-mcp"]
-    }
-  }
+	"mcpServers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -248,11 +255,13 @@ gemini mcp add viberag -- npx viberag-mcp
 <summary><strong>OpenAI Codex</strong> — <code>~/.codex/config.toml</code></summary>
 
 **CLI Command:**
+
 ```bash
 codex mcp add viberag -- npx viberag-mcp
 ```
 
 **Manual Setup:** Add to your config.toml:
+
 ```toml
 [mcp_servers.viberag]
 command = "npx"
@@ -271,14 +280,15 @@ args = ["viberag-mcp"]
 **Config:** `~/.config/opencode/opencode.json` (Linux/macOS) or `%APPDATA%/opencode/opencode.json` (Windows)
 
 **Manual Setup:** Add to your existing opencode.json:
+
 ```json
 {
-  "mcp": {
-    "viberag": {
-      "type": "local",
-      "command": ["npx", "-y", "viberag-mcp"]
-    }
-  }
+	"mcp": {
+		"viberag": {
+			"type": "local",
+			"command": ["npx", "-y", "viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -294,14 +304,15 @@ args = ["viberag-mcp"]
 <summary><strong>Windsurf</strong> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
 
 **Manual Setup:** Merge into your existing mcp_config.json:
+
 ```json
 {
-  "mcpServers": {
-    "viberag": {
-      "command": "npx",
-      "args": ["viberag-mcp"]
-    }
-  }
+	"mcpServers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -317,14 +328,15 @@ args = ["viberag-mcp"]
 **Config:** `~/Library/Application Support/Zed/settings.json` (macOS) or `~/.config/zed/settings.json` (Linux)
 
 **Manual Setup:** Merge into your existing settings.json:
+
 ```json
 {
-  "context_servers": {
-    "viberag": {
-      "command": "npx",
-      "args": ["viberag-mcp"]
-    }
-  }
+	"context_servers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
 }
 ```
 
@@ -344,6 +356,7 @@ args = ["viberag-mcp"]
 <summary><strong>JetBrains IDEs</strong> — Settings UI</summary>
 
 **Manual Setup:**
+
 1. Open Settings → Tools → AI Assistant → MCP
 2. Click "Add Server"
 3. Set name: `viberag`
@@ -356,8 +369,114 @@ args = ["viberag-mcp"]
 
 </details>
 
+
+### Exposed MCP Tools
+
+| Tool                       | Description                                          |
+| -------------------------- | ---------------------------------------------------- |
+| `codebase_search`          | Semantic, keyword, or hybrid search for code         |
+| `codebase_parallel_search` | Run multiple search strategies in parallel           |
+| `viberag_index`            | Index the codebase (incremental by default)          |
+| `viberag_status`           | Get index status, file count, and embedding provider |
+| `viberag_watch_status`     | Get file watcher status for auto-indexing            |
+
+#### `codebase_search`
+
+The primary search tool. Finds code by meaning, not just keywords.
+
+**Search Modes:**
+
+| Mode         | Best For                                     |
+| ------------ | -------------------------------------------- |
+| `hybrid`     | Most queries (default) - combines both       |
+| `semantic`   | Conceptual queries ("how does auth work?")   |
+| `exact`      | Symbol names, specific strings               |
+| `definition` | Direct symbol lookup ("where is X defined?") |
+| `similar`    | Find code similar to a snippet               |
+
+**Key Parameters:**
+
+- `query` - Natural language search query
+- `mode` - Search mode (default: `hybrid`)
+- `limit` - Max results (default: 10, max: 100)
+- `bm25_weight` - Balance keyword vs semantic (0-1, default: 0.3)
+- `filters` - Path, type, and metadata filters
+
+**Example:**
+
+```json
+{
+	"query": "authentication middleware",
+	"mode": "hybrid",
+	"limit": 15,
+	"filters": {
+		"path_not_contains": ["test", "mock"],
+		"is_exported": true
+	}
+}
+```
+
+#### `codebase_parallel_search`
+
+Run multiple search strategies simultaneously and merge results. Best for comprehensive exploration.
+
+**Use Cases:**
+
+- Compare semantic vs keyword results
+- Search related concepts together
+- Test different weight settings
+
+**Example:**
+
+```json
+{
+	"searches": [
+		{"query": "authentication", "mode": "semantic", "limit": 10},
+		{"query": "auth login JWT", "mode": "exact", "limit": 10},
+		{"query": "user session", "mode": "hybrid", "bm25_weight": 0.5, "limit": 10}
+	],
+	"merge_results": true,
+	"merge_strategy": "rrf",
+	"merged_limit": 20
+}
+```
+
+#### `viberag_index`
+
+Manually trigger indexing. Normally not needed as file watching handles updates automatically.
+
+**Parameters:**
+
+- `force` - Full reindex ignoring cache (default: `false`)
+
+#### `viberag_status`
+
+Check index health and configuration.
+
+**Returns:**
+
+- File count, chunk count
+- Embedding provider and dimensions
+- Schema version
+- Last update timestamp
+- Warmup status (ready, initializing, etc.)
+
+#### `viberag_watch_status`
+
+Check the file watcher for auto-indexing.
+
+**Returns:**
+
+- Whether watching is active
+- Number of files being watched
+- Pending changes count
+- Last update timestamp
+
+
 ## CLI Commands
 
+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) |
@@ -375,20 +494,21 @@ Choose your embedding provider during `/init`:
 
 ### Local Model - Offline, Free
 
-| Model      | Quant | Download | RAM   |
-| ---------- | ----- | -------- | ----- |
+| Model      | Quant | Download | RAM    |
+| ---------- | ----- | -------- | ------ |
 | Qwen3-0.6B | Q8    | ~700MB   | ~1.5GB |
 
 - Works completely offline, no API key required
 - Initial indexing may take time; future updates are incremental
+- Works great for code and natural language (docs, docstrings, code comments, etc.)
 
 ### Cloud Providers - Fastest, Best Quality
 
-| Provider | Model                  | Dims | Cost      | Get API Key                                                                    |
-| -------- | ---------------------- | ---- | --------- | ------------------------------------------------------------------------------ |
-| Gemini   | gemini-embedding-001   | 1536 | Free tier | [Google AI Studio](https://aistudio.google.com)                                |
-| Mistral  | codestral-embed        | 1024 | $0.10/1M  | [Mistral Console](https://console.mistral.ai/api-keys/)                        |
-| OpenAI   | text-embedding-3-small | 1536 | $0.02/1M  | [OpenAI Platform](https://platform.openai.com/api-keys)                        |
+| Provider | Model                  | Dims | Cost      | Get API Key                                             |
+| -------- | ---------------------- | ---- | --------- | ------------------------------------------------------- |
+| Gemini   | gemini-embedding-001   | 1536 | Free tier | [Google AI Studio](https://aistudio.google.com)         |
+| Mistral  | codestral-embed        | 1024 | $0.10/1M  | [Mistral Console](https://console.mistral.ai/api-keys/) |
+| OpenAI   | text-embedding-3-small | 1536 | $0.02/1M  | [OpenAI Platform](https://platform.openai.com/api-keys) |
 
 - **Gemini** - Free tier available, great for getting started
 - **Mistral** - Code-optimized embeddings for technical content
@@ -412,14 +532,15 @@ VibeRAG works best when AI agents use **sub-agents for exploration tasks**. This
 
 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** |
+| Approach             | Context Usage | Token Efficiency |
+| -------------------- | ------------- | ---------------- |
+| Direct viberag calls | 24k tokens    | Baseline         |
+| Sub-agent delegation | 3k tokens     | **8x better**    |
 
 ### Platform-Specific Guidance
 
 #### Claude Code
+
 ```
 # For exploration tasks, use the Task tool:
 Task(subagent_type='Explore', prompt='Use viberag to find how authentication works')
@@ -430,60 +551,69 @@ Task(subagent_type='Explore', prompt='Search login flows')   # with this one
 ```
 
 Add to your `CLAUDE.md`:
+
 ```markdown
 When exploring the codebase, use Task(subagent_type='Explore') and instruct it
 to use codebase_search or codebase_parallel_search. This keeps the main context clean.
 ```
 
 #### VS Code Copilot
+
 - Use **Agent HQ** to delegate exploration to background agents
 - Background agents can iterate with viberag without blocking your session
 - Use `/delegate` to hand off exploration tasks to Copilot coding agent
 
 #### Cursor
+
 - Enable **Agent mode** for multi-step exploration
 - Agent mode can orchestrate multiple viberag searches autonomously
 - Consider the [Sub-Agents MCP server](https://playbooks.com/mcp/shinpr-sub-agents) for Claude Code-style delegation
 
 #### Windsurf
+
 - **Cascade** automatically plans multi-step tasks
 - Enable **Turbo Mode** for autonomous exploration
 - Cascade's planning agent will orchestrate viberag calls efficiently
 
 #### Roo Code
+
 - Use **Architect mode** for exploration and understanding
 - **Boomerang tasks** coordinate complex multi-mode workflows
 - Each mode (Architect, Code, Debug) can use viberag with focused context
 
 #### Gemini CLI
+
 - Create **extensions** that scope viberag tools for specific tasks
 - Extensions can bundle viberag with custom prompts for specialized exploration
 - Use `gemini mcp add viberag` then reference in extension configs
 
 #### OpenAI Codex
+
 - Use **Agents SDK** to orchestrate viberag as an MCP tool
 - Codex can run as an MCP server itself for multi-agent setups
 - Approval modes control how autonomously Codex explores
 
 #### JetBrains IDEs
+
 - **Junie** agent handles multi-step exploration autonomously
 - **Claude Agent** integration provides sub-agent-like capabilities
 - Access viberag through AI Chat with multi-agent support
 
 #### Zed
+
 - Use **External Agents** (Claude Code, Codex, Gemini CLI) for exploration
 - Set `auto_approve` in settings for autonomous agent operation
 - ACP (Agent Client Protocol) enables BYO agent integration
 
 ### Quick Lookup vs Exploration
 
-| Task Type | Recommended Approach |
-|-----------|---------------------|
-| "Where is function X defined?" | Direct `codebase_search` with mode='definition' |
-| "What file handles Y?" | Direct `codebase_search` - single query |
-| "How does authentication work?" | **Sub-agent** - needs multiple searches |
-| "Find all API endpoints" | **Sub-agent** or `codebase_parallel_search` |
-| "Understand the data flow" | **Sub-agent** - iterative exploration |
+| Task Type                       | Recommended Approach                            |
+| ------------------------------- | ----------------------------------------------- |
+| "Where is function X defined?"  | Direct `codebase_search` with mode='definition' |
+| "What file handles Y?"          | Direct `codebase_search` - single query         |
+| "How does authentication work?" | **Sub-agent** - needs multiple searches         |
+| "Find all API endpoints"        | **Sub-agent** or `codebase_parallel_search`     |
+| "Understand the data flow"      | **Sub-agent** - iterative exploration           |
 
 ### For Platforms Without Sub-Agents
 
@@ -491,13 +621,13 @@ Use `codebase_parallel_search` to run multiple search strategies in a single cal
 
 ```json
 {
-  "searches": [
-    {"query": "authentication", "mode": "semantic"},
-    {"query": "auth login", "mode": "exact"},
-    {"query": "user session", "mode": "hybrid", "bm25_weight": 0.5}
-  ],
-  "merge_results": true,
-  "merge_strategy": "rrf"
+	"searches": [
+		{"query": "authentication", "mode": "semantic"},
+		{"query": "auth login", "mode": "exact"},
+		{"query": "user session", "mode": "hybrid", "bm25_weight": 0.5}
+	],
+	"merge_results": true,
+	"merge_strategy": "rrf"
 }
 ```
 

package/dist/cli/components/CleanWizard.js

@@ -51,7 +51,9 @@ export function CleanWizard({ projectRoot, viberagDir, onComplete, onCancel, add
             setStep('processing');
             performCleanup(false);
         }
-    }, [projectScopeEditors, onCancel]);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- performCleanup is stable
+    [projectScopeEditors, onCancel]);
     // Perform the actual cleanup
     const performCleanup = useCallback(async (cleanMcp) => {
         const fs = await import('node:fs/promises');

package/dist/cli/components/McpSetupWizard.js

@@ -50,7 +50,7 @@ function MultiSelect({ items, selected, onToggle, onSubmit, highlightIndex, onHi
                 onToggle(item.id);
             }
         }
-        else if (key.return) {
+        else if (key.return && selected.size > 0) {
             onSubmit();
         }
     });
@@ -122,13 +122,9 @@ export function McpSetupWizard({ step, config, projectRoot, showPrompt, onStepCh
     }, []);
     // Submit selection
     const handleSubmitSelection = useCallback(() => {
-        if (selected.size === 0) {
-            onCancel();
-            return;
-        }
         onStepChange('configure', { selectedEditors: Array.from(selected) });
         setCurrentEditorIndex(0);
-    }, [selected, onStepChange, onCancel]);
+    }, [selected, onStepChange]);
     // Get current editor being configured
     const selectedEditorIds = config.selectedEditors ?? [];
     const currentEditorId = selectedEditorIds[currentEditorIndex];
@@ -244,7 +240,10 @@ export function McpSetupWizard({ step, config, projectRoot, showPrompt, onStepCh
             React.createElement(Box, { marginTop: 1 },
                 React.createElement(Text, { dimColor: true },
                     selected.size,
-                    " selected | \u2191/\u2193 move, Space toggle, Enter confirm, Esc cancel"))));
+                    " selected | \u2191/\u2193 move, Space toggle,",
+                    ' ',
+                    selected.size > 0 ? 'Enter confirm, ' : '',
+                    "Esc cancel"))));
     }
     // Step: Configure each editor
     if (step === 'configure' && currentEditor) {

package/dist/mcp/index.js

@@ -13,7 +13,7 @@ import { createMcpServer } from './server.js';
 import { configExists, Indexer } from '../rag/index.js';
 // Use current working directory as project root (same behavior as CLI)
 const projectRoot = process.cwd();
-const { server, startWatcher, stopWatcher } = createMcpServer(projectRoot);
+const { server, startWatcher, stopWatcher, startWarmup } = createMcpServer(projectRoot);
 // Handle shutdown signals
 async function shutdown(signal) {
     console.error(`[viberag-mcp] Received ${signal}, shutting down...`);
@@ -26,11 +26,22 @@ process.on('SIGTERM', () => shutdown('SIGTERM'));
 server.start({
     transportType: 'stdio',
 });
-// Start watcher and sync index after server is running
+// Start warmup, watcher, and sync index after server is running
 // Use setImmediate to ensure server.start() completes first
 setImmediate(async () => {
+    // Start warmup FIRST (most important for tool responsiveness)
+    // This runs in background - tools will wait for it to complete
+    try {
+        if (await configExists(projectRoot)) {
+            startWarmup();
+            console.error('[viberag-mcp] Warmup started');
+        }
+    }
+    catch (error) {
+        console.error('[viberag-mcp] Failed to start warmup:', error instanceof Error ? error.message : error);
+    }
+    // Start watcher (will queue any changes during sync)
     try {
-        // Start watcher first (will queue any changes during sync)
         await startWatcher();
     }
     catch (error) {

package/dist/mcp/server.d.ts

@@ -8,18 +8,22 @@
  */
 import { FastMCP } from 'fastmcp';
 import { FileWatcher } from './watcher.js';
+import { WarmupManager } from './warmup.js';
 /**
- * MCP server with file watcher.
+ * MCP server with file watcher and warmup manager.
  */
 export interface McpServerWithWatcher {
     server: FastMCP;
     watcher: FileWatcher;
+    warmupManager: WarmupManager;
     /** Start the watcher (call after server.start) */
     startWatcher: () => Promise<void>;
     /** Stop the watcher (call before exit) */
     stopWatcher: () => Promise<void>;
+    /** Start warmup (call after server.start) */
+    startWarmup: () => void;
 }
 /**
- * Create and configure the MCP server with file watcher.
+ * Create and configure the MCP server with file watcher and warmup manager.
  */
 export declare function createMcpServer(projectRoot: string): McpServerWithWatcher;