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

Core Capabilities

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).

Search & Filtering

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.

Plugin System

Modular Architecture: Built-in, npm, and local plugin support with override detection.
Versioned Structure: /src/plugins/<name>/<version>/ 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.

Advanced Features

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.

Technical Stack

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

🔌 Plugin System

VibeScout features a powerful plugin system for extending functionality:

Plugin Sources

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

Plugin Capabilities

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

Plugin Management

# 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

Plugin Development

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

Global Installation

npm install -g @sevenseconds/vibescout

💻 CLI Usage

Web UI

Launch the interactive dashboard: ``bash vibescout ui ``

Advanced Logging

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 ```

Indexing & Search

# 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

Two-Phase Search (MCP Only)

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

Performance Profiling

# 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:

Download Models: In an online environment, let VibeScout download the models first, or download them manually from Hugging Face.
Enable Offline Mode: Toggle Offline Mode in Settings or run with the --offline flag.
Local Path: Use --models-path <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

Claude Desktop / Gemini CLI

Add VibeScout to your configuration:

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

📄 License

MIT License. See LICENSE for details.

VibeScout