VibeScout

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

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:

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:

vibescout ui

Advanced Logging

Control terminal output verbosity:

# 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

{
  "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)

{
  "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:

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