Vibecode CLI

██╗   ██╗██╗██████╗ ███████╗ ██████╗ ██████╗ ██████╗ ███████╗
██║   ██║██║██╔══██╗██╔════╝██╔════╝██╔═══██╗██╔══██╗██╔════╝
██║   ██║██║██████╔╝█████╗  ██║     ██║   ██║██║  ██║█████╗
╚██╗ ██╔╝██║██╔══██╗██╔══╝  ██║     ██║   ██║██║  ██║██╔══╝
 ╚████╔╝ ██║██████╔╝███████╗╚██████╗╚██████╔╝██████╔╝███████╗
  ╚═══╝  ╚═╝╚═════╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

Build Software with Discipline — AI coding with guardrails

---

What is Vibecode?

Vibecode is a CLI tool that brings discipline to AI-assisted development. Instead of chaotic prompt-and-pray coding, Vibecode enforces a structured workflow:

1. Define what you want (Intake)
2. Design how it works (Blueprint)
3. Agree on deliverables (Contract)
4. Build with AI assistance
5. Review against criteria
6. Ship with confidence

---

Quick Start

# Install globally
npm install -g @nclamvn/vibecode-cli

# Initialize in your project
cd your-project
vibecode init

# Start guided session
vibecode start

That's it! Vibecode will guide you through the entire process.

---

Philosophy

AI as Pipeline, not Tool

Traditional approach:

Human → AI → Code → ???

Vibecode approach:

Human → Contract → AI Pipeline → Validated Code → Ship
         ↑                              │
         └──────── Feedback Loop ───────┘

Core Principles

Principle	Description
Contract-First	Lock scope before building. No scope creep.
Evidence-Based	Every build produces diff, logs, screenshots
Iterative	Build → Test → Fix loop until tests pass
Disciplined	State machine prevents skipping steps

---

Workflow

┌─────────────────────────────────────────────────────────────────┐
│                        VIBECODE WORKFLOW                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  PHASE A: PLANNING                                              │
│  ┌──────┐   ┌───────────┐   ┌──────────┐   ┌────────┐          │
│  │ INIT │ → │  INTAKE   │ → │ BLUEPRINT│ → │CONTRACT│          │
│  └──────┘   └───────────┘   └──────────┘   └────────┘          │
│                                                   │             │
│                                                   ▼             │
│                                              ┌────────┐         │
│                                              │  LOCK  │         │
│                                              └────────┘         │
│                                                   │             │
│  PHASE B: EXECUTION                               │             │
│                                                   ▼             │
│  ┌────────┐   ┌───────┐   ┌────────┐   ┌──────────┐            │
│  │SHIPPED │ ← │REVIEW │ ← │ BUILD  │ ← │   PLAN   │            │
│  └────────┘   └───────┘   └────────┘   └──────────┘            │
│                   │             ▲                               │
│                   │             │                               │
│                   └─────────────┘                               │
│                   (if failed, rebuild)                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Commands Reference

Phase A: Planning

Command	Description	Options
vibecode init	Initialize workspace	-f, --force -q, --quiet
vibecode start	Start guided session	-r, --resume
vibecode status	Show current state	--json -v, --verbose
vibecode lock	Lock contract, generate spec hash	-d, --dry-run -f, --force
vibecode doctor	Check installation health	—

Phase B: Execution

Command	Description	Options
vibecode plan	Create execution plan	—
vibecode build	Build with AI	See Build Flags below
vibecode review	Review against criteria	--skip-manual
vibecode snapshot	Create release	--patch --minor --major
vibecode config	Manage settings	--show --provider <name>

---

Build Flags

The build command supports multiple modes:

# Manual build
vibecode build --start      # Start building
vibecode build --evidence   # Capture git diff
vibecode build --complete   # Mark as done

# AI-powered build
vibecode build --auto       # Single AI build with Claude Code

# Iterative build (recommended)
vibecode build --iterate              # Build → Test → Fix loop
vibecode build --iterate --max 5      # Max 5 iterations
vibecode build --iterate --strict     # Exit with error if fails

How --iterate Works

┌─────────────────────────────────────────────────────────┐
│                  ITERATIVE BUILD LOOP                   │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────┐                                            │
│  │  START  │                                            │
│  └────┬────┘                                            │
│       ▼                                                 │
│  ┌─────────┐     ┌─────────┐     ┌─────────┐           │
│  │  BUILD  │ ──▶ │  TEST   │ ──▶ │ ANALYZE │           │
│  │(Claude) │     │(npm test│     │ ERRORS  │           │
│  └─────────┘     │ + lint) │     └────┬────┘           │
│       ▲          └─────────┘          │                │
│       │                               ▼                │
│       │          ┌─────────┐     ┌─────────┐           │
│       └──────────│GENERATE │ ◀── │ ERRORS? │           │
│                  │FIX PROMPT│     └────┬────┘           │
│                  └─────────┘          │ No             │
│                                       ▼                │
│                                  ┌─────────┐           │
│                                  │  DONE!  │           │
│                                  └─────────┘           │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

Examples

Example 1: Simple CLI Calculator

mkdir my-calculator && cd my-calculator
vibecode init

vibecode start
# Describe: "CLI calculator with add, subtract, multiply, divide"

vibecode start  # Continue to blueprint
vibecode start  # Continue to contract
vibecode lock   # Lock the contract

vibecode plan   # Generate execution plan
vibecode build --iterate  # Build until tests pass

vibecode review    # Review the build
vibecode snapshot  # Create v1.0.0

Example 2: Landing Page

mkdir landing && cd landing
vibecode init
vibecode start
# Describe: "Modern landing page with hero, features, pricing, and contact form"

# ... follow the workflow
vibecode build --iterate --max 3

Example 3: Using with Existing Project

cd my-existing-project
vibecode init
vibecode start
# Describe your feature/fix

vibecode build --auto  # Single AI build

---

Project Structure

After vibecode init, your project will have:

your-project/
├── .vibecode/
│   ├── vibecode.yaml      # Configuration
│   ├── state.json         # State machine
│   ├── sessions/          # Session data
│   │   └── abc123/        # Session ID
│   │       ├── intake.md
│   │       ├── blueprint.md
│   │       ├── contract.md
│   │       ├── plan.md
│   │       ├── coder_pack.md
│   │       └── evidence/
│   │           ├── changes.diff
│   │           ├── build.log
│   │           └── screenshots/
│   └── logs/
│       └── audit.log
└── ... your code

---

State Machine

Vibecode enforces a strict state machine to prevent skipping steps:

State	Description	Next States
INIT	Fresh workspace	INTAKE_CAPTURED
INTAKE_CAPTURED	Description recorded	BLUEPRINT_DRAFTED
BLUEPRINT_DRAFTED	Architecture designed	CONTRACT_DRAFTED
CONTRACT_DRAFTED	Scope defined	CONTRACT_LOCKED
CONTRACT_LOCKED	Ready to build	PLAN_CREATED
PLAN_CREATED	Plan generated	BUILD_IN_PROGRESS
BUILD_IN_PROGRESS	Building...	BUILD_DONE
BUILD_DONE	Build complete	REVIEW_PASSED / REVIEW_FAILED
REVIEW_PASSED	QA passed	SHIPPED
REVIEW_FAILED	QA failed	BUILD_IN_PROGRESS
SHIPPED	Released!	—

---

Requirements

• Node.js >= 18.0.0
• Claude Code CLI (for --auto and --iterate modes)

  npm install -g @anthropic-ai/claude-code

---

Configuration

CLAUDE.md

Create a CLAUDE.md file in your project root to provide context to Claude Code:

# Project Rules

- Use TypeScript for all new files
- Follow existing code style
- Write tests for new features
- No console.log in production code

This will be automatically injected when using --auto or --iterate.

---

Troubleshooting

"No Vibecode workspace found"

Run vibecode init first.

"Invalid transition"

You're trying to skip a step. Check current state with vibecode status.

"Claude Code CLI not found"

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Build keeps failing

1. Check vibecode status --verbose
2. Look at .vibecode/sessions/<id>/evidence/build.log
3. Try vibecode build --iterate --max 5 for more attempts

---

Links

• npm: https://www.npmjs.com/package/@nclamvn/vibecode-cli
• Issues: https://github.com/nclamvn/vibecode-cli/issues

---

License

MIT © Lam

---

Credits

Powered by Claude Code

---

"Contract LOCKED = License to Build"