vibe-coding-mcp 0.1.1
MCP server and CLI for the Vibe Coding methodology
License: MIT
Requires Python: >=3.10
Keywords: vibe-coding, mcp, ai, cursor, coding, methodology

# Vibe Coding 🎸

A structured methodology for AI-assisted development that actually works.

**The Problem:** AI coding assistants are powerful but chaotic. They lose context, break working code, and turn 5-minute tasks into hour-long debugging sessions.

**The Solution:** Vibe Coding breaks work into small, verified chunks with clear boundaries. Each chunk is isolated, tested, and locked before moving on.

## Quick Start

```bash
# Install globally with pipx
pipx install vibe-coding-mcp

# Initialize a new project
mkdir my-project && cd my-project
vibe init --turbo

# Restart Cursor, then start coding!
# The AI will automatically use chunk-based workflow
```

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                     VIBE CODING WORKFLOW                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. PLAN         Use Opus 4.5 to draft PROJECT_BRIEF.md       │
│        ↓                                                        │
│   2. HANDOFF      Switch to smaller model (Codex mini, etc.)   │
│        ↓                                                        │
│   3. START        AI calls start_chunk("001-feature")          │
│        ↓          Creates branch: chunk/001-feature            │
│   4. BUILD        AI writes code, you verify                   │
│        ↓                                                        │
│   5. COMPLETE     AI calls complete_chunk("summary")           │
│        ↓          Auto-commits, merges, tags                   │
│   6. CONTINUE     Click "Keep Changes" → say "continue"        │
│        ↓                                                        │
│   7. REPEAT       Next chunk starts fresh                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Recommended Model Strategy

| Phase | Model | Why |
|-------|-------|-----|
| **Planning** | Claude Opus 4.5 | Better at architecture, breaking down problems |
| **Building** | GPT Codex mini, Sonnet | Fast, cheap, good at following structured plans |

The brief is your handoff document. A well-written brief lets smaller models execute reliably.

## Key Concepts

### Chunks
Small, focused units of work (ideally 5-10 minutes of AI effort). Each chunk:
- Lives on its own git branch
- Has clear success criteria
- Gets locked after completion (can't accidentally break it)

### Chunk 0 Pattern
Your first chunk (`000-setup`) always creates dependencies and project structure:
```
pyproject.toml → folder structure → README skeleton
```
After chunk 0, you install dependencies, then continue.

### Two Modes

| Mode | Use When | AI Behavior |
|------|----------|-------------|
| **CREATE** | Building new features | Can create files, broad changes |
| **EDIT** | Fixing bugs, tweaks | Surgical precision, minimal changes |

### Turbo Mode 🏎️
Auto-approves chunks as they complete. Great for flow state, with git tags for easy rollback.

```bash
vibe init --turbo    # Enable turbo mode
vibe turbo --off     # Switch to manual approval mid-project
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `vibe init` | Initialize project for vibe coding |
| `vibe init --turbo` | Initialize with auto-merge enabled |
| `vibe status` | Show current chunk status |
| `vibe pause` | Pause mid-chunk (stashes work) |
| `vibe resume` | Resume paused chunk |
| `vibe revert <chunk>` | Rollback to before a chunk |
| `vibe turbo --on/--off` | Toggle turbo mode |
| `vibe logs` | View diagnostic notes |

> **Note:** In Cursor, you typically don't need `vibe approve`—just click "Keep Changes" and say "continue". The CLI commands are mainly for status checks and recovery.

## MCP Tools (for AI)

The AI uses these tools automatically via Cursor's MCP integration:

| Tool | Purpose |
|------|---------|
| `start_chunk(name, mode)` | Begin a new chunk |
| `complete_chunk(summary)` | Mark chunk done |
| `log_note(note)` | Save diagnostic notes |
| `get_status()` | Check current state |

## Installation

### Prerequisites
- Python 3.10+
- Git
- [Cursor IDE](https://cursor.sh) with MCP support
- pipx (`brew install pipx` or `pip install pipx`)

### Install

```bash
pipx install vibe-coding-mcp
```

### Project Setup

```bash
# Create new project
mkdir my-app && cd my-app

# Initialize (creates .git, .cursorrules, updates MCP config)
vibe init --turbo

# Restart Cursor to load MCP server

# Create PROJECT_BRIEF.md with your requirements
# Start chatting - AI handles the rest!
```

## Example Session

```
You: Build a CLI note-taking app following PROJECT_BRIEF.md

AI: [calls start_chunk("000-setup", "create")]
    Creating project structure...
    
    ⏸️ Run these commands then say 'continue':
    python3 -m venv venv
    source venv/bin/activate
    pip install -e .

You: [Click "Keep Changes"] → [Run commands in terminal] → "continue"

AI: [calls start_chunk("001-core", "create")]
    Implementing note storage...
    [calls complete_chunk("Added Note class with JSON persistence")]
    
    ┌─────────────────────────────────────┐
    │ ✅ 001-core                         │
    │ Committed: ✓  Merged: ✓  Tagged: ✓  │
    └─────────────────────────────────────┘

You: [Click "Keep Changes"] → "continue"

AI: [calls start_chunk("002-cli", "create")]
    Adding CLI commands...
    ...
```

> **Cursor Workflow:** After each chunk, click **"Keep Changes"** to accept the code, then type **"continue"** or **"ready"** in the chat to proceed to the next chunk.

## Best Practices

### DO ✅
- Keep chunks small (5-10 min AI work)
- Write clear PROJECT_BRIEF.md upfront
- Test after each chunk
- Use `vibe pause` if interrupted

### DON'T ❌
- Cram multiple features into one chunk
- Skip verification between chunks
- Fight the AI—reject and restart if stuck
- Manually edit `.vibe_state.json`

## Tested Projects

Built and verified with vibe coding:
- ✅ CLI note-taking app
- ✅ URL shortener API (FastAPI + SQLite)
- ✅ Markdown link checker
- ✅ Git hooks installer

## Troubleshooting

### "Not on main branch"
```bash
git checkout main
vibe status
```

### Chunk stuck / corrupted state
```bash
rm .vibe_state.json
vibe init  # Re-initialize
```

### Need to undo a chunk
```bash
vibe revert 003-feature  # Rolls back to before chunk 003
```

## Philosophy

> "The goal isn't to make AI write all your code. It's to make AI *reliably* write *chunks* of your code while you maintain control."

Vibe coding is about:
1. **Predictability** over speed
2. **Small wins** over big bangs
3. **Verification** over trust
4. **Rollback safety** over YOLO commits

## License

MIT

## Contributing

PRs welcome! Please follow the vibe coding methodology when contributing. 😉