Setup

vibe --setup # Run setup wizard
vibe --help # Show all options
vibe --version # Show version

Interactive Mode Features:

- Chat-style conversation with context retention

- Live tool execution with progress indicators

- Session persistence and history

- Markdown rendering support

- Multiple themes and customization

- Slash commands for quick actions

Installation

bash

Quick Start

Claude Desktop
Place the system instructions in your project's system instructions or custom instructions:

1. Open Claude Desktop

2. Navigate to project settings

3. Add the contents of VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md to the system instructions field

4. Save and restart Claude Desktop
Version 0 3 1 Global Installation Synchronization
- Fixed global/local version synchronization issues

- Enhanced clean build process for installations

- Improved packaging workflow for NPM publication
Version 0 2 3 Interactive Repl Setup Wizard
- Interactive REPL Mode with chat-style interface and session persistence

- Enhanced Setup Wizard with automatic first-run detection

- Configuration Templates in src/config-templates/

- Performance Improvements with optimized memory usage

- Unified CLI Binary - single vibe command for all operations
Install Globally Recommended
npm install -g vibe-coder-mcp@latest
Run Setup Wizard On First Use
vibe --setup
Or Use Instantly With Npx No Installation
npx vibe-coder-mcp@latest --setup

The setup wizard will:
1. ✅ Configure your OpenRouter API key
2. ✅ Set up project directories
3. ✅ Create configuration files from templates
4. ✅ Validate your environment
5. ✅ Get you ready to use all features!

Recommended Install Globally For The Vibe Command

npm install -g vibe-coder-mcp@latest

Or Run Instantly Without Installation

npx vibe-coder-mcp@latest

Installation Methods

Global Installation (Recommended)

bash
npm install -g vibe-coder-mcp@latest

No Installation Needed

npx vibe-coder-mcp@latest
npx vibe-coder-mcp@latest "research React best practices"

Local Project Installation

bash
npm install vibe-coder-mcp
npx vibe-coder-mcp "map the codebase structure"

Command Line Usage

bash

Quick Integration Guide

Vibe-Coder MCP integrates seamlessly with any MCP-compatible client. Here's how to configure it:

Option 2 Global Installation

First Install Globally
npm install -g vibe-coder-mcp

Then configure:
- Command/URL: vibe
- Arguments: (leave empty)
- Environment Variables: Same as Option 1

Claude Desktop Specific Configuration

For Claude Desktop users, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key",
        "VIBE_PROJECT_ROOT": "/path/to/your/project",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

See example_claude_desktop_config.json for a complete example.

Zero Configuration For Cli Users

Simple Configuration For Mcp Clients

json
{
"env": {
"OPENROUTER_API_KEY": "your_key_here",
"VIBE_PROJECT_ROOT": "/path/to/your/project"
}
}

- One Variable: VIBE_PROJECT_ROOT replaces multiple directory configs

- Auto-Detection: CLI automatically detects project root

- Backward Compatible: Legacy variables still supported

Environment Configuration
Required: You need an OpenRouter API key to use Vibe Coder MCP.
Set Up Environment Variables
Option 1: Using Setup Wizard (Recommended for v0.2.3+)

bash

Run The Interactive Setup Wizard

vibe --setup

Validate Your Setup

Option 2: Environment Variables

bash

Optional Unified Project Root Configuration

VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
VIBE_PROJECT_ROOT="/path/to/your/project"
VIBE_USE_PROJECT_ROOT_AUTO_DETECTION="true"

Directory Configuration Unified Simplified

🆕 Unified Configuration (Recommended)
- VIBE_PROJECT_ROOT: Single variable for all project operations (automatic detection enabled by default for CLI)
- VIBE_USE_PROJECT_ROOT_AUTO_DETECTION: Enable automatic project root detection for CLI users (default: "true")
- VIBE_CODER_OUTPUT_DIR: Where generated files are saved (default: ./VibeCoderOutput/)

Legacy Configuration (Still Supported)
- CODE_MAP_ALLOWED_DIR: Security boundary for code analysis (fallback if VIBE_PROJECT_ROOT not set)
- VIBE_TASK_MANAGER_READ_DIR: Security boundary for task manager operations (fallback if VIBE_PROJECT_ROOT not set)

Auto-Detection Benefits:
- Zero Configuration: CLI users get automatic project root detection
- Context Aware: Different behavior for CLI vs MCP client usage
- Intelligent Fallbacks: 5-priority resolution chain ensures reliable operation

Mcp Client Setup

Configure your AI assistant to connect to Vibe Coder MCP:

Cli Usage Guide

Vibe Coder includes a powerful command-line interface with multiple modes for direct interaction with all tools.

Interactive Setup Wizard Enhanced In V0 2 3

First Time Setup Runs Automatically On First Use
vibe --setup
Reconfigure Existing Installation
vibe --reconfigure

Development Setup Advanced

If you want to contribute to development or run from source, follow the detailed setup guide below.

Development Setup Guide

For developers who want to run from source or contribute to the project.

Step 1 Prerequisites

1. Check Node.js Version:
Open a terminal or command prompt.
Run node -v
Ensure the output shows v20.0.0 or higher (required).
If not installed or outdated: Download from nodejs.org.

2. Check Git Installation:
Open a terminal or command prompt.
Run git --version
If not installed: Download from git-scm.com.

3. Get OpenRouter API Key:
Visit openrouter.ai
Create an account if you don't have one.
Navigate to API Keys section.
Create a new API key and copy it.
Keep this key handy for Step 4.

Step 3 Run The Setup Script

Choose the appropriate script for your operating system:

For Windows:
1. In your terminal (still in the vibe-coder-mcp directory), run:

   setup.bat

   

2. Wait for the script to complete (it will install dependencies, build the project, and create necessary directories).
3. If you see any error messages, refer to the Troubleshooting section below.

For macOS or Linux:
1. Make the script executable:

   chmod +x setup.sh

   

2. Run the script:

   ./setup.sh

   

3. Wait for the script to complete.
4. If you see any error messages, refer to the Troubleshooting section below.

The script performs these actions:
Checks Node.js version (v20+ required)
Installs all dependencies via npm
Creates necessary VibeCoderOutput/ subdirectories
Builds the TypeScript project
Creates configuration from templates if not present (v0.2.3+)
Sets executable permissions (on Unix systems)

Note: The setup process is now faster (v0.2.3+) with optimized dependency installation and simplified build process.

Step 4 Configure Environment Variables

New in v0.2.3: Configuration templates are provided in src/config-templates/ for easy setup.

Option A Use The Setup Wizard Recommended

vibe --setup

The wizard will guide you through configuration and create all necessary files.

Option B Manual Configuration

1. Copy templates (if not already done by setup script):

   cp src/config-templates/.env.template .env

   cp src/config-templates/llm_config.template.json llm_config.json

   cp src/config-templates/mcp-config.template.json mcp-config.json

   

2. Edit .env file with your configuration:

Openrouter Configuration Required

OPENROUTER_API_KEY="your_actual_api_key_here"
Optional Configurations
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

   GEMINI_MODEL=google/gemini-2.5-flash-preview-05-20
5 2 Add The Vibe Coder Configuration
1.  Open the settings file identified above in a text editor.

2.  Find the "mcpServers": { ... } JSON object. If it doesn't exist, you may need to create it (ensure the overall file remains valid JSON). For example, an empty file might become {"mcpServers": {}}.

3.  Add the following configuration block inside the curly braces {} of the mcpServers object. If other servers are already listed, add a comma , after the previous server's closing brace } before pasting this block.

json
// This is the unique identifier for this MCP server instance within your client's settings
"vibe-coder-mcp": {
// Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH
"command": "node",
// Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point
// !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
"args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"],
// Sets the current working directory for the server process when it runs
// !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
"cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
// Defines the communication transport protocol between the client and server
"transport": "stdio",
// Environment variables to be passed specifically to the Vibe Coder server process when it starts
// API Keys should be in the .env file, NOT here
"env": {
// Absolute path to the LLM configuration file used by Vibe Coder
// !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
"LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json",
// Sets the logging level for the server
"LOG_LEVEL": "debug",
// Specifies the runtime environment
"NODE_ENV": "production",
// Directory where Vibe Coder tools will save their output files
// !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
"VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput",
// 🆕 Unified project root for all tools (recommended)
// This single variable configures all tools with the same project boundary
"VIBE_PROJECT_ROOT": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
// Legacy variables (optional - used as fallbacks if VIBE_PROJECT_ROOT not set)
"CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src",
"VIBE_TASK_MANAGER_READ_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP"
},
// A boolean flag to enable (false) or disable (true) this server configuration
"disabled": false,
// A list of tool names that the MCP client is allowed to execute automatically
"autoApprove": [
"research",
"rules-generator",
"user-stories-generator",
"task-list-generator",
"prd-generator",
"fullstack-starter-kit-generator",
"refactor-code",
"git-summary",
"run-workflow",
"map-codebase"
]
}

4.  CRUCIAL: Replace all placeholder paths (like /path/to/your/vibe-coder-mcp/...) with the correct absolute paths on your system where you cloned the repository. Use forward slashes / for paths, even on Windows (e.g., C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js). Incorrect paths are the most common reason the server fails to connect.

5.  Save the settings file.

6.  Completely close and restart your AI assistant application (Cursor, VS Code, Claude Desktop, etc.) for the changes to take effect.

Step 6 Test Your Configuration
1. Start Your AI Assistant:

    Completely restart your AI assistant application.

2. Test a Simple Command:

    Type a test command like: Research modern JavaScript frameworks
3. Check for Proper Response:

    If working correctly, you should receive a research response.

    If not, check the Troubleshooting section below.
Complete Project Setup
"Set up a new e-commerce project with React frontend and Node.js backend"
Workflow Configuration
Workflows are defined in the workflows.json file located in the root directory of the project. This file contains predefined sequences of tool calls that can be executed with a single command.
Quick Start Examples

Running Locally Optional

While the primary use is integration with an AI assistant (using stdio), you can run the server directly for testing:

Running Modes

Production Mode (Stdio):

    npm start

    

Logs go to stderr (mimics AI assistant launch)
Use NODE_ENV=production

Development Mode (Stdio, Pretty Logs):

    npm run dev

    

Logs go to stdout with pretty formatting
Requires nodemon and pino-pretty
Use NODE_ENV=development

SSE Mode (HTTP Interface):
``bash

Path Configuration Problems

Problem: "Path not found" or "Access denied" errors
- Solution: Use absolute paths with forward slashes (/) in all configurations
- Windows: Convert paths like C:\Users\name to C:/Users/name
- Permissions: Ensure the user has read/write access to configured directories
- Environment Variables: Verify VIBE_CODER_OUTPUT_DIR and VIBE_PROJECT_ROOT are set correctly (or legacy variables CODE_MAP_ALLOWED_DIR and VIBE_TASK_MANAGER_READ_DIR)

Getting Help

If issues persist:
1. Check existing issues at GitHub Issues
2. Enable debug logging: LOG_LEVEL=debug
3. Collect error messages and logs
4. Create a new issue with:
- Node.js version (node -v`)
- Operating system
- Error messages
- Steps to reproduce