viberag 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +315 -34
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,17 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
|
|
2
2
|
|
|
3
3
|
# VIBERAG
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Free, Open Source, Local / Offline Capable, Container-Free Semantic Search For Your Codebase**
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Viberag is fully local, offline capable MCP server for local codebase search.
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- **Multi-language support** - TypeScript, JavaScript, Python, Go, Rust, and more
|
|
9
|
+
- Semantic codebase search
|
|
10
|
+
- Keyboard codebase search
|
|
11
|
+
- Hybrid codebase search (with tunable parameters)
|
|
12
|
+
|
|
13
|
+
VibeRAG automatically indexes your codebase into a local container-free vector database ([lancedb](https://lancedb.com/)). Every time you make a change, the indexes are automatically updated.
|
|
15
14
|
|
|
16
15
|
## Install
|
|
17
16
|
|
|
@@ -29,47 +28,329 @@ viberag
|
|
|
29
28
|
# Run /init to configure and index
|
|
30
29
|
/init
|
|
31
30
|
|
|
32
|
-
#
|
|
31
|
+
# In addition to allowing Agents to search via the MCP server,
|
|
32
|
+
# you can search yourself via the CLI.
|
|
33
33
|
/search authentication handler
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
+
### Example
|
|
37
|
+
|
|
38
|
+
When using a coding agent like [Claude Code](https://claude.ai/code), add `use viberag` to your prompt.
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
────────────────────────────────────────────────────────────────────
|
|
42
|
+
> How is authentication handled in this repo? use viberag
|
|
43
|
+
────────────────────────────────────────────────────────────────────
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
> **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.
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
## Features
|
|
50
|
+
|
|
51
|
+
- **CLI based setup** - CLI commands and wizards for setup, editor integration, and configuration
|
|
52
|
+
- **Semantic code search** - Find code by meaning, not just keywords
|
|
53
|
+
- **Flexible embeddings** - Local model (offline, free) or cloud providers (Gemini, Mistral, OpenAI)
|
|
54
|
+
- **MCP server** - Works with Claude Code, Cursor, VS Code Copilot, and more
|
|
55
|
+
- **Incremental indexing** - Only re-embeds changed files
|
|
56
|
+
- **Multi-language support** - TypeScript, JavaScript, Python, Go, Rust, and more
|
|
57
|
+
|
|
58
|
+
### How It Works:
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
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.
|
|
62
|
+
|
|
63
|
+
This ensures a more exhaustive search of your codebase so you don't miss important files and features that are relevant to your changes or refactor.
|
|
64
|
+
|
|
65
|
+
### Great for Monorepos
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
### Embedding Models
|
|
70
|
+
- 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.
|
|
71
|
+
|
|
72
|
+
- 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.
|
|
73
|
+
|
|
74
|
+
|
|
36
75
|
## MCP Server Setup
|
|
37
76
|
|
|
38
|
-
VibeRAG includes an MCP server that integrates with AI coding tools.
|
|
77
|
+
VibeRAG includes an MCP server that integrates with AI coding tools.
|
|
78
|
+
|
|
79
|
+
### Setup Wizard
|
|
80
|
+
|
|
81
|
+
Run `/mcp-setup` in the VibeRAG CLI for interactive setup:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
# Start viberag
|
|
85
|
+
$ viberag
|
|
86
|
+
|
|
87
|
+
# Run the setup wizard (after having initialized with /init)
|
|
88
|
+
$ /mcp-setup
|
|
89
|
+
|
|
90
|
+
# Automatic configuration wizard
|
|
91
|
+
╭───────────────────────────────────────────────────────────────╮
|
|
92
|
+
│ MCP Setup Wizard │
|
|
93
|
+
│ │
|
|
94
|
+
│ Select AI coding tool(s) to configure: │
|
|
95
|
+
│ (Space to toggle, Enter to confirm) │
|
|
96
|
+
│ │
|
|
97
|
+
│ > [x] Claude Code (auto-setup) │
|
|
98
|
+
│ [ ] Cursor (auto-setup) │
|
|
99
|
+
│ [ ] Gemini CLI (global config) │
|
|
100
|
+
│ [ ] JetBrains IDEs (manual setup) │
|
|
101
|
+
│ [ ] OpenAI Codex (global config) │
|
|
102
|
+
│ [ ] OpenCode (global config) │
|
|
103
|
+
│ [ ] Roo Code (auto-setup) │
|
|
104
|
+
│ [ ] VS Code Copilot (auto-setup) │
|
|
105
|
+
│ [ ] Windsurf (global config) │
|
|
106
|
+
│ [ ] Zed (global config) │
|
|
107
|
+
│ │
|
|
108
|
+
│ 1 selected | ↑/↓ move, Space toggle, Enter confirm, Esc cancel│
|
|
109
|
+
╰───────────────────────────────────────────────────────────────╯
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The wizard can auto-configure project-level configs and merge into global configs.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
### Project-Specific Configs
|
|
117
|
+
|
|
118
|
+
These editors use per-project config files that VibeRAG can auto-create.
|
|
119
|
+
|
|
120
|
+
<details>
|
|
121
|
+
<summary><strong>Claude Code</strong> — <code>.mcp.json</code></summary>
|
|
122
|
+
|
|
123
|
+
**CLI Command:**
|
|
124
|
+
```bash
|
|
125
|
+
claude mcp add viberag -- npx viberag-mcp
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Manual Setup:**
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"mcpServers": {
|
|
132
|
+
"viberag": {
|
|
133
|
+
"command": "npx",
|
|
134
|
+
"args": ["viberag-mcp"]
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
**Verify:** Run `/mcp` in Claude Code, look for "viberag: connected"
|
|
141
|
+
|
|
142
|
+
[Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)
|
|
143
|
+
|
|
144
|
+
</details>
|
|
145
|
+
|
|
146
|
+
<details>
|
|
147
|
+
<summary><strong>Cursor</strong> — <code>.cursor/mcp.json</code></summary>
|
|
148
|
+
|
|
149
|
+
**Manual Setup:**
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"mcpServers": {
|
|
153
|
+
"viberag": {
|
|
154
|
+
"command": "npx",
|
|
155
|
+
"args": ["viberag-mcp"]
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**Verify:** Settings → Cursor Settings → MCP, verify "viberag" shows with toggle enabled
|
|
162
|
+
|
|
163
|
+
[Documentation](https://docs.cursor.com/context/model-context-protocol)
|
|
164
|
+
|
|
165
|
+
</details>
|
|
166
|
+
|
|
167
|
+
<details>
|
|
168
|
+
<summary><strong>Roo Code</strong> — <code>.roo/mcp.json</code></summary>
|
|
169
|
+
|
|
170
|
+
**Manual Setup:**
|
|
171
|
+
```json
|
|
172
|
+
{
|
|
173
|
+
"mcpServers": {
|
|
174
|
+
"viberag": {
|
|
175
|
+
"command": "npx",
|
|
176
|
+
"args": ["viberag-mcp"]
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
**Verify:** Click MCP icon in Roo Code pane header, verify "viberag" appears in server list
|
|
183
|
+
|
|
184
|
+
[Documentation](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
|
|
185
|
+
|
|
186
|
+
</details>
|
|
187
|
+
|
|
188
|
+
<details>
|
|
189
|
+
<summary><strong>VS Code Copilot</strong> — <code>.vscode/mcp.json</code></summary>
|
|
190
|
+
|
|
191
|
+
**Manual Setup:**
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"servers": {
|
|
195
|
+
"viberag": {
|
|
196
|
+
"command": "npx",
|
|
197
|
+
"args": ["viberag-mcp"]
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
> **Note:** VS Code uses `"servers"` instead of `"mcpServers"`
|
|
204
|
+
|
|
205
|
+
**Verify:** Cmd/Ctrl+Shift+P → "MCP: List Servers", verify "viberag" appears
|
|
206
|
+
|
|
207
|
+
[Documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
|
|
208
|
+
|
|
209
|
+
</details>
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
### Global Configs
|
|
214
|
+
|
|
215
|
+
These editors use global config files. VibeRAG can merge into existing configs.
|
|
216
|
+
|
|
217
|
+
<details>
|
|
218
|
+
<summary><strong>Gemini CLI</strong> — <code>~/.gemini/settings.json</code></summary>
|
|
219
|
+
|
|
220
|
+
**CLI Command:**
|
|
221
|
+
```bash
|
|
222
|
+
gemini mcp add viberag -- npx viberag-mcp
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Manual Setup:** Add to your existing settings.json:
|
|
226
|
+
```json
|
|
227
|
+
{
|
|
228
|
+
"mcpServers": {
|
|
229
|
+
"viberag": {
|
|
230
|
+
"command": "npx",
|
|
231
|
+
"args": ["viberag-mcp"]
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
**Verify:** Run `/mcp` in Gemini CLI, look for "viberag" in server list
|
|
238
|
+
|
|
239
|
+
[Documentation](https://googlegemini.io/gemini-cli/docs/mcp)
|
|
240
|
+
|
|
241
|
+
</details>
|
|
242
|
+
|
|
243
|
+
<details>
|
|
244
|
+
<summary><strong>OpenAI Codex</strong> — <code>~/.codex/config.toml</code></summary>
|
|
245
|
+
|
|
246
|
+
**CLI Command:**
|
|
247
|
+
```bash
|
|
248
|
+
codex mcp add viberag -- npx viberag-mcp
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
**Manual Setup:** Add to your config.toml:
|
|
252
|
+
```toml
|
|
253
|
+
[mcp_servers.viberag]
|
|
254
|
+
command = "npx"
|
|
255
|
+
args = ["viberag-mcp"]
|
|
256
|
+
```
|
|
39
257
|
|
|
40
|
-
|
|
258
|
+
**Verify:** Run `/mcp` in Codex TUI, look for "viberag" in server list
|
|
41
259
|
|
|
42
|
-
|
|
43
|
-
| ------------------- | -------------------------------------------------- | --------------------------------------------------- |
|
|
44
|
-
| **Claude Code** | `.mcp.json` | Auto or `claude mcp add viberag -- npx viberag-mcp` |
|
|
45
|
-
| **Cursor** | `.cursor/mcp.json` | Auto |
|
|
46
|
-
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add viberag -- npx viberag-mcp` |
|
|
47
|
-
| **JetBrains IDEs** | Settings UI | Manual in Settings → AI Assistant → MCP |
|
|
48
|
-
| **OpenAI Codex** | `~/.codex/config.toml` | `codex mcp add viberag -- npx viberag-mcp` |
|
|
49
|
-
| **OpenCode** | `~/.config/opencode/opencode.json` | Manual merge |
|
|
50
|
-
| **Roo Code** | `.roo/mcp.json` | Auto |
|
|
51
|
-
| **VS Code Copilot** | `.vscode/mcp.json` | Auto |
|
|
52
|
-
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Manual merge |
|
|
53
|
-
| **Zed** | `~/Library/Application Support/Zed/settings.json` | Manual merge |
|
|
260
|
+
[Documentation](https://codex.openai.com/docs/tools/mcp-servers)
|
|
54
261
|
|
|
55
|
-
|
|
262
|
+
</details>
|
|
56
263
|
|
|
57
|
-
|
|
264
|
+
<details>
|
|
265
|
+
<summary><strong>OpenCode</strong> — <code>~/.config/opencode/opencode.json</code></summary>
|
|
58
266
|
|
|
267
|
+
**Config:** `~/.config/opencode/opencode.json` (Linux/macOS) or `%APPDATA%/opencode/opencode.json` (Windows)
|
|
268
|
+
|
|
269
|
+
**Manual Setup:** Add to your existing opencode.json:
|
|
59
270
|
```json
|
|
60
271
|
{
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
272
|
+
"mcp": {
|
|
273
|
+
"viberag": {
|
|
274
|
+
"type": "local",
|
|
275
|
+
"command": ["npx", "-y", "viberag-mcp"]
|
|
276
|
+
}
|
|
277
|
+
}
|
|
67
278
|
}
|
|
68
279
|
```
|
|
69
280
|
|
|
70
|
-
> **Note:**
|
|
281
|
+
> **Note:** OpenCode uses `"mcp"` key and requires `"type": "local"` with command as an array
|
|
282
|
+
|
|
283
|
+
**Verify:** Check MCP servers list in OpenCode, verify "viberag" appears and is enabled
|
|
284
|
+
|
|
285
|
+
[Documentation](https://opencode.ai/docs/tools/mcp)
|
|
286
|
+
|
|
287
|
+
</details>
|
|
288
|
+
|
|
289
|
+
<details>
|
|
290
|
+
<summary><strong>Windsurf</strong> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
|
|
291
|
+
|
|
292
|
+
**Manual Setup:** Merge into your existing mcp_config.json:
|
|
293
|
+
```json
|
|
294
|
+
{
|
|
295
|
+
"mcpServers": {
|
|
296
|
+
"viberag": {
|
|
297
|
+
"command": "npx",
|
|
298
|
+
"args": ["viberag-mcp"]
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
**Verify:** Click Plugins icon in Cascade panel, verify "viberag" shows in plugin list
|
|
305
|
+
|
|
306
|
+
[Documentation](https://docs.windsurf.com/windsurf/cascade/mcp)
|
|
307
|
+
|
|
308
|
+
</details>
|
|
309
|
+
|
|
310
|
+
<details>
|
|
311
|
+
<summary><strong>Zed</strong> — <code>~/Library/Application Support/Zed/settings.json</code></summary>
|
|
312
|
+
|
|
313
|
+
**Config:** `~/Library/Application Support/Zed/settings.json` (macOS) or `~/.config/zed/settings.json` (Linux)
|
|
314
|
+
|
|
315
|
+
**Manual Setup:** Merge into your existing settings.json:
|
|
316
|
+
```json
|
|
317
|
+
{
|
|
318
|
+
"context_servers": {
|
|
319
|
+
"viberag": {
|
|
320
|
+
"command": "npx",
|
|
321
|
+
"args": ["viberag-mcp"]
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
> **Note:** Zed uses `"context_servers"` instead of `"mcpServers"`
|
|
328
|
+
|
|
329
|
+
**Verify:** Open Agent Panel settings, verify "viberag" shows green indicator
|
|
330
|
+
|
|
331
|
+
[Documentation](https://zed.dev/docs/ai/mcp)
|
|
332
|
+
|
|
333
|
+
</details>
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
### UI-Based Setup
|
|
338
|
+
|
|
339
|
+
<details>
|
|
340
|
+
<summary><strong>JetBrains IDEs</strong> — Settings UI</summary>
|
|
341
|
+
|
|
342
|
+
**Manual Setup:**
|
|
343
|
+
1. Open Settings → Tools → AI Assistant → MCP
|
|
344
|
+
2. Click "Add Server"
|
|
345
|
+
3. Set name: `viberag`
|
|
346
|
+
4. Set command: `npx`
|
|
347
|
+
5. Set args: `viberag-mcp`
|
|
348
|
+
|
|
349
|
+
**Verify:** Settings → Tools → AI Assistant → MCP, verify "viberag" shows green in Status column
|
|
350
|
+
|
|
351
|
+
[Documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html)
|
|
71
352
|
|
|
72
|
-
|
|
353
|
+
</details>
|
|
73
354
|
|
|
74
355
|
## CLI Commands
|
|
75
356
|
|