VibeScout: Local Code Intelligence & MCP Server

A high-performance Model Context Protocol (MCP) server and Web Dashboard for local semantic code search and AI-powered assistance. VibeScout transforms your codebase into a searchable, chat-ready knowledge base using local or cloud-based AI providers.

🚀 Features

$3

- Web Dashboard: A modern React-based UI for visual searching, chatting with your code, and managing your knowledge base.
- Semantic Code Search: Fast vector-based search with BGE reranking for extreme technical accuracy.
- Visual Dependency Graph: Explore architecture visually with Symbol Intelligence panel and Circular Dependency Detection.
- AI-Powered Chat: Persistent context chat with RAG-powered code understanding.
- Real-time File Watching: Automatic re-indexing when files change (chokidar-based).

$3

- Category Pre-Filtering: Database-level filtering by Code/Docs for maximum performance (default: Code-only).
- Token Count Preview: Preview search results before consuming tokens with two-phase search (MCP only).
- Git Metadata: Enhanced search with author, date, churn level, and commit history.
- Dependencies Display: View imports/exports for each search result with source tracking.
- Search Persistence: Results persist across tab switches for seamless workflow.
- Framework Detection: Auto-detects Next.js, React Router, Vue, Angular, and 10+ frameworks.

$3

- Modular Architecture: Built-in, npm, and local plugin support with override detection.
- Versioned Structure: /src/plugins/// for built-in plugins.
- Compatibility Checking: Auto-disables incompatible plugins with clear warnings.
- Runtime Toggle: Enable/disable plugins via UI or config file.
- Sandboxed Execution: Isolated worker threads for safe plugin operation.

$3

- Two-Phase Search: Preview search metadata before consuming tokens (MCP only).
- AI Smart Questions: "Generate Best Question" analyzes code to suggest optimal chat starting points.
- Adaptive Concurrency: Automatically detects provider rate limits and dynamically scales request rates.
- Real-time Activity (SSE): Instant system event streaming via Server-Sent Events.
- AI Inspector (Debug): Chrome DevTools-style panel to inspect prompts, payloads, and responses.
- IDE Integration: "Open in Editor" with line-level navigation for VS Code and Cursor.
- Performance Profiling: Built-in profiling with Chrome DevTools flame graphs for optimizing indexing and search performance.

$3

- Hono-Powered Backend: Ultra-low latency with standard Web Fetch API support.
- Multi-Language Support: TypeScript/JS, Python, Go, Java, Kotlin, Dart, Markdown, JSON, TOML, XML.
- Hybrid Storage: Local LanceDB or Cloudflare Vectorize for cloud embeddings.
- AI Reranker: Optional second-pass re-sorting with local models.
- Fully Offline Mode: Strict local-only operation, no remote model downloads.

🤖 Supported Providers

| Provider | Type | Description |
| :--- | :--- | :--- |
| Local | Built-in | Transformers.js (BGE, MiniLM). High-speed, zero config. |
| Ollama | Local API | Full support for local models like Llama 3, Mistral, and Nomic. |
| Z.AI | Cloud | BigModel.cn integration. Supports GLM-4 and dedicated Coding Plans. |
| Bedrock | Cloud | AWS Bedrock (Claude 3, Titan). Supports AWS Profiles. |
| Gemini | Cloud | Google Generative AI (1.5 Flash/Pro) and specialized embeddings. |
| OpenAI | Cloud | Standard OpenAI API or compatible (DeepSeek, Groq, etc). |
| Cloudflare | Cloud | Workers AI & Vectorize integration for cloud-native indexing. |
| LM Studio | Local API | OpenAI-compatible local server preset. |

🔌 Plugin System

VibeScout features a powerful plugin system for extending functionality:

$3

- Built-in Plugins: Shipped with VibeScout (/src/plugins///)
- npm Packages: Install via vibescout plugin install
- Local Plugins: Place in ~/.vibescout/plugins/

$3

- Extractors: Custom code extraction strategies (e.g., framework-specific metadata)
- Providers: Custom embedding/summarizer providers
- Commands: CLI commands for framework-specific operations

$3

``bash

List plugins

vibescout plugin list

Install from npm

vibescout plugin install vibescout-plugin-nextjs

Install specific version

vibescout plugin install vibescout-plugin-nextjs@beta

Uninstall

vibescout plugin uninstall vibescout-plugin-nextjs

Enable/Disable (via Web UI or config.json)

Plugins are stored in ~/.vibescout/config.json

`

$3

See /docs/ directory for:
- plugin-guide.md - Getting started
- plugin-api.md - API reference
- plugin-architecture.md - Design patterns
- plugin-example.md - Complete example
- two-phase-search.md - Two-phase search with token count preview
- profiling-guide.md - Performance profiling and optimization

🛠 Installation

$3

`bash
npm install -g @sevenseconds/vibescout
`

💻 CLI Usage

$3

Launch the interactive dashboard:
`bash
vibescout ui
`

$3

Control terminal output verbosity:
`bash

Default is INFO (concise)

vibescout ui --log-level warn

Full debug output (alias for --log-level debug)

vibescout ui --verbose
`

$3

`bash

Index a project manually

vibescout index ./my-app "My Project"

Semantic search via terminal

vibescout search "how does the auth flow work?"

Reset the database (clear all data)

vibescout reset

Or via npm

npm run reset-db
`

$3

When using VibeScout with Claude Desktop, Cursor, or other MCP clients, you can preview search results before consuming tokens:

Phase 1: Preview Token Count
`json
{
"name": "search_code",
"arguments": {
"query": "authentication flow",
"limit": 20,
"previewOnly": true
}
}
`

This returns metadata without actual code:
- Result count
- Total tokens (from stored counts during indexing)
- Average relevance score
- Recommendation on whether to proceed

Phase 2: Fetch Results (if tokens are acceptable)
`json
{
"name": "search_code",
"arguments": {
"query": "authentication flow",
"limit": 10,
"previewOnly": false
}
}
`

Benefits:
- Avoid unexpected token consumption
- Adjust limit parameter based on preview
- Use more specific filters if token count is high
- Backward compatible: omit previewOnly for existing behavior

$3


`bash

Profile with 100% sampling (most detailed)

vibescout --profile index ./my-app "My Project"

Profile with 10% sampling (lower overhead)

vibescout --profile --profile-sampling 0.1 search "authentication"

Dedicated profiling command

vibescout profile index --folder ./my-app --sampling 1.0

View traces in chrome://tracing

Traces saved to ~/.vibescout/profiles/

`

Profiling Features:
- Zero overhead when disabled (default)
- Chrome DevTools-compatible flame graphs
- Configurable sampling rates (0.0-1.0) to reduce overhead
- Category-based sampling (indexing, search, embedding, database)
- Web UI dashboard at http://localhost:3000/performance

See docs/profiling-guide.md for detailed documentation.

🔒 Offline Mode

To use VibeScout in a restricted environment without internet access:

1. Download Models: In an online environment, let VibeScout download the models first, or download them manually from Hugging Face.
2. Enable Offline Mode: Toggle Offline Mode in Settings or run with the --offline flag.
3. Local Path: Use --models-path if your models are stored in a non-standard directory.

When enabled, VibeScout sets allowRemoteModels: false and disables all attempts to connect to the Hugging Face Hub.

🔌 Client Integration

$3

Add VibeScout to your configuration:

`json
{
"mcpServers": {
"vibescout": {
"command": "vibescout",
"args": ["--mcp", "stdio"]
}
}
}
``

📄 License

MIT License. See LICENSE for details.