Getting Started with Vibe

This guide will help you install Vibe and create your first SPEC-driven project in under 5 minutes.

Prerequisites

Before installing Vibe, ensure you have:

Node.js 18.0.0 or higher
npm 7.0.0 or higher
Claude Code (for slash commands and MCP integration)

Check your versions:

node --version  # Should be v18.0.0+
npm --version   # Should be 7.0.0+

Installation

1. Install Vibe globally

npm install -g @su-record/vibe

This will:

✅ Install the Vibe CLI
✅ Install @su-record/hi-ai MCP server (38 development tools)

Note: The MCP server is registered per-project when you run vibe init.

2. Verify installation

vibe help

Expected output:

Vibe - SPEC-driven AI coding framework

Usage:
  vibe <command> [options]

Commands:
  init              Initialize Vibe in current project
  spec <name>       Create specification
  plan <name>       Generate technical plan
  tasks <name>      Decompose into tasks
  run <task>        Execute task
  ...

Initialize Your First Project

1. Navigate to your project directory

cd /path/to/your/project

2. Initialize Vibe

vibe init

This will:

✅ Create .vibe/ directory structure
✅ Register MCP server for this project only (local configuration)

Verify MCP server (in your project directory):

claude mcp list

Expected output:

vibe: node /path/to/@su-record/vibe/node_modules/@su-record/hi-ai/dist/index.js - ✓ Connected

Project structure created:

your-project/
├── .vibe/
│   ├── config.json          # Vibe configuration
│   ├── specs/               # Specifications (EARS format)
│   ├── features/            # BDD Feature files (Gherkin)
│   ├── plans/               # Technical plans
│   ├── tasks/               # Task breakdowns
│   ├── guides/              # Task implementation guides
│   └── reports/             # Analysis reports
└── CLAUDE.md                # Tech stack documentation (optional)

3. (Optional) Document your tech stack

Create CLAUDE.md in your project root for automatic tech stack detection:

# CLAUDE.md

## Tech Stack

### Backend
- Framework: FastAPI 0.104+
- Database: PostgreSQL 17
- Cache: Redis 7.2

### Frontend
- Framework: Flutter 3.24+
- State Management: Provider

This helps Vibe agents select the right tech stack automatically.

Your First SPEC

Let's create a specification for a simple feature: "push notification settings"

Step 1: Create SPEC

vibe spec "push notification settings"

You'll be asked 6 questions:

Q1. Why? (Business value)

Reduce app churn from excessive notifications
Current: 15% weekly churn
Target: <10% weekly churn

Q2. Who? (Users and scale)

All users (100k+ DAU)
95% mobile, 5% web

Q3. What? (Features)

6-category notification toggle system:
- Likes (default: ON)
- Comments (default: ON)
- Follows (default: ON)
- Mentions (default: ON)
- Feed updates (default: OFF)
- Marketing (default: OFF)

Q4. How? (Technical requirements)

Performance: P95 < 500ms
Infrastructure: Redis caching
Security: Rate limiting (100 req/min)

Q5. When? (Timeline)

3 days (24 hours development time)
Priority: HIGH

Q6. With What? (Tech stack)

Backend: FastAPI + PostgreSQL
Frontend: Flutter + Provider
Push: Firebase Cloud Messaging

Result:

✅ Created: .vibe/specs/push-notification-settings.md

Step 2: Review SPEC

cat .vibe/specs/push-notification-settings.md

Expected format:

# SPEC: Push Notification Settings

## Metadata
- Created: 2025-11-17
- Priority: HIGH
- Language: en

## 1. Why (Business Value)
Reduce app churn from excessive notifications
- Current: 15% weekly churn
- Target: <10% weekly churn

## 2. Who (Users)
- All users (100k+ DAU)
- 95% mobile, 5% web

## 3. What (Features)

### REQ-001: Notification Category Toggles
**WHEN** user opens notification settings
**THEN** system SHALL display 6 category toggles

#### Acceptance Criteria
- [ ] Display 6 categories with ON/OFF toggles
- [ ] Show default state for each category
- [ ] Persist changes to database

### REQ-002: Default Settings
**WHEN** new user registers
**THEN** system SHALL apply default notification settings

#### Acceptance Criteria
- [ ] Likes: ON
- [ ] Comments: ON
- [ ] Follows: ON
- [ ] Mentions: ON
- [ ] Feed updates: OFF
- [ ] Marketing: OFF

...

Generate Technical Plan

Step 3: Generate plan

vibe plan "push notification settings"

Result:

✅ Created: .vibe/plans/push-notification-settings.md

Summary:
- 3 Phases: Backend → Frontend → FCM Integration
- Timeline: 24 hours (3 days)
- Cost: +$0.50/month (Redis + FCM)
- Stack Reuse: 100% existing infrastructure

Step 4: Review plan

cat .vibe/plans/push-notification-settings.md

Expected sections:

Architecture Overview: System design and components
Database Schema: Table structures and migrations
API Design: Endpoints and request/response formats
Frontend Components: UI structure and state management
Cost Analysis: Infrastructure and operational costs
Timeline: Phase-based breakdown with estimates
Risk Assessment: Potential blockers and mitigation

Decompose into Tasks

Step 5: Generate tasks

vibe tasks "push notification settings"

Result:

✅ Created: .vibe/tasks/push-notification-settings.md

Task Breakdown:
- Total: 19 tasks
- Phase 1 (Backend): 8 tasks
- Phase 2 (Frontend): 8 tasks
- Phase 3 (FCM): 3 tasks
- Dependency graph included

Step 6: Review tasks

cat .vibe/tasks/push-notification-settings.md

Expected format:

# TASKS: Push Notification Settings

## Phase 1: Backend Development (8 hours)

### Task 1-1: Database Migration ⬜
**Description**: Create user_notification_settings table

**Implementation**:
1. Create Alembic migration file
2. Add 6 boolean columns for categories
3. Set default values
4. Add foreign key to users table

**Acceptance Criteria**:
- [ ] Migration file created
- [ ] All 6 columns present
- [ ] Defaults match SPEC
- [ ] Foreign key constraint added

**Dependencies**: None
**Estimated Time**: 1 hour

---

### Task 1-2: Settings Repository ⬜
**Description**: Create data access layer

**Implementation**:
1. Create NotificationSettingsRepository class
2. Implement get_settings(user_id)
3. Implement update_settings(user_id, settings)
4. Add database session handling

**Acceptance Criteria**:
- [ ] Repository class with type hints
- [ ] CRUD methods implemented
- [ ] Unit tests passing

**Dependencies**: Task 1-1
**Estimated Time**: 1.5 hours

...

Execute Tasks

Step 7: Run first task

vibe run "Task 1-1"

What happens:

Task Guide Generated: Creates .vibe/guides/task-1-1.md with detailed implementation steps
AI Agent Selected: Chooses appropriate agent (e.g., Backend Python Expert)
Implementation: Executes task with step-by-step guidance
Verification: Checks acceptance criteria
Status Update: Marks task as ⬜ → ✅

Result:

✅ Task 1-1 completed

Files changed:
- backend/alembic/versions/xxx_add_notification_settings.py (created)

Next task: Task 1-2 (Settings Repository)
Run: vibe run "Task 1-2"

Step 8: Run entire phase

vibe run --phase 1

This executes all tasks in Phase 1 sequentially, respecting dependencies.

Verify Implementation

Step 9: Verify against SPEC

vibe verify "push notification settings"

Result:

📊 Verification Report

✅ REQ-001: Notification Category Toggles (3/3 criteria)
✅ REQ-002: Default Settings (6/6 criteria)
✅ REQ-003: Update API (4/4 criteria)
⚠️ REQ-004: Performance Target (2/3 criteria)
  ❌ P95 latency: 620ms (target: <500ms)

Overall: 85% complete (15/17 criteria)

Recommendations:
1. Add Redis caching to reduce latency
2. Optimize database query in get_settings()

Report saved: .vibe/reports/verification-2025-11-17.md

Advanced Features

Code Analysis

Analyze code quality before committing:

vibe analyze --code

Output:

📊 Code Quality Report

Overall Score: 85/100 (B+)

Findings:
- High complexity: src/service.py (CC: 15)
- Low cohesion: src/utils.py (0.3)

Recommendations:
1. Refactor src/service.py into 3 modules
2. Extract unrelated utilities from src/utils.py

UI Mockup

Preview UI before implementation:

vibe ui "notification settings screen with 6 toggles"

Output:

┌─────────────────────────────────────────┐
│      Notification Settings              │
├─────────────────────────────────────────┤
│                                          │
│  Likes                    [●────] ON    │
│  Comments                 [●────] ON    │
│  Follows                  [●────] ON    │
│  Mentions                 [●────] ON    │
│  Feed updates             [────○] OFF   │
│  Marketing                [────○] OFF   │
│                                          │
│         ┌─────────────────────┐          │
│         │    Save Changes     │          │
│         └─────────────────────┘          │
└─────────────────────────────────────────┘

Architecture Diagram

Generate Mermaid diagrams:

vibe diagram --er

Output:

erDiagram
    users ||--o{ user_notification_settings : has
    users {
        uuid id PK
        string email
        datetime created_at
    }
    user_notification_settings {
        uuid id PK
        uuid user_id FK
        boolean likes
        boolean comments
        boolean follows
        boolean mentions
        boolean feed_updates
        boolean marketing
    }

Slash Commands in Claude Code

Use these commands directly in Claude Code chat:

/vibe.spec "push notification settings"
/vibe.plan "push notification settings"
/vibe.tasks "push notification settings"
/vibe.run "Task 1-1"
/vibe.verify "push notification settings"

Advantages:

No terminal switching
Inline results in chat
Access to 38 MCP tools
Memory preservation across sessions

Configuration

.vibe/config.json

{
  "language": "ko",
  "agents": {
    "default": "backend-python-expert"
  },
  "mcp": {
    "enabled": true,
    "servers": ["vibe"]
  },
  "quality": {
    "max_complexity": 10,
    "max_nesting": 3,
    "max_function_length": 20
  }
}

Next Steps

Now that you've completed your first workflow:

Core Concepts - Understand SPEC-driven methodology
Command Reference - Learn all CLI commands
MCP Integration - Explore 38 development tools
Agents Guide - Master 7 specialized agents
Best Practices - Production-grade workflows

Troubleshooting

MCP server not connected

MCP servers are registered per-project in Vibe. If you see "No MCP servers configured":

# Make sure you're in your project directory
cd /path/to/your/project

# Re-run vibe init (safe to run multiple times)
vibe init

# Verify (must be in project directory)
claude mcp list

Important: You must run claude mcp list from within your project directory where you ran vibe init.

Command not found: vibe

# Check global npm bin path
npm config get prefix

# Should be in PATH (usually /usr/local or ~/.nvm/versions/node/vXX/bin)
echo $PATH

# Reinstall if needed
npm install -g @su-record/vibe

Slash commands not working

Ensure Claude Code is running and MCP server is connected:

claude mcp list
# Should show: vibe - ✓ Connected

Ready to build with Vibe? Let's go! 🚀

← Back to Home | Next: Core Concepts →

Getting‐Started - su-record/vibe GitHub Wiki

Getting Started with Vibe

Prerequisites

Installation

1. Install Vibe globally

2. Verify installation

Initialize Your First Project

1. Navigate to your project directory

2. Initialize Vibe

3. (Optional) Document your tech stack

Your First SPEC

Step 1: Create SPEC

Step 2: Review SPEC

Generate Technical Plan

Step 3: Generate plan

Step 4: Review plan

Decompose into Tasks

Step 5: Generate tasks

Step 6: Review tasks

Execute Tasks

Step 7: Run first task

Step 8: Run entire phase

Verify Implementation

Step 9: Verify against SPEC

Advanced Features

Code Analysis

UI Mockup

Architecture Diagram

Slash Commands in Claude Code

Configuration

.vibe/config.json

Next Steps

Troubleshooting

MCP server not connected

Command not found: vibe

Slash commands not working

⚠️ GitHub.com Fallback ⚠️

Getting‐Started - su-record/vibe GitHub Wiki

Getting Started with Vibe

Prerequisites

Installation

1. Install Vibe globally

2. Verify installation

Initialize Your First Project

1. Navigate to your project directory

2. Initialize Vibe

3. (Optional) Document your tech stack

Your First SPEC

Step 1: Create SPEC

Step 2: Review SPEC

Generate Technical Plan

Step 3: Generate plan

Step 4: Review plan

Decompose into Tasks

Step 5: Generate tasks

Step 6: Review tasks

Execute Tasks

Step 7: Run first task

Step 8: Run entire phase

Verify Implementation

Step 9: Verify against SPEC

Advanced Features

Code Analysis

UI Mockup

Architecture Diagram

Slash Commands in Claude Code

Configuration

.vibe/config.json

Next Steps

Troubleshooting

MCP server not connected

Command not found: vibe

Slash commands not working

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️