Vibecode CLI

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

Build Software with Discipline — AI coding with guardrails

![npm version](https://www.npmjs.com/package/@nclamvn/vibecode-cli)
![License: MIT](https://opensource.org/licenses/MIT)

---

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

`bash


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

$3

Traditional approach:
`
Human → AI → Code → ???
`

Vibecode approach:
`
Human → Contract → AI Pipeline → Validated Code → Ship
↑ │
└──────── Feedback Loop ───────┘
`

$3

| 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

$3

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

$3

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

---

Build Flags

The build command supports multiple modes:

`bash


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
`

$3

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

---

Examples

$3

`bash
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
`

$3

`bash
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
`

$3

`bash
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)
`bash
npm install -g @anthropic-ai/claude-code
`

---

Configuration

$3

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

`markdown


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

$3

Run vibecode init first.

$3

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

$3

Install Claude Code:
`bash
npm install -g @anthropic-ai/claude-code
`

$3

1. Check vibecode status --verbose
2. Look at .vibecode/sessions//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"