vibe-kanban

Original source / Raw SKILL.md

---
name: vibe-kanban
description: Manage AI coding agents on a visual Kanban board. Run parallel agents through a To Do→In Progress→Review→Done flow with automatic git worktree isolation and GitHub PR creation.
allowed-tools: Read Write Bash Grep Glob
metadata:
  tags: vibe-kanban, kanban, kanbanview, multi-agent, git-worktree, github-pr, task-management, claude-code, codex, gemini, open-code, mcp
  platforms: Claude, Codex, Gemini, OpenCode
  keyword: kanbanview
  version: 1.2.0
  source: "https://github.com/BloopAI/vibe-kanban"
  verified: 2026-02-22
  verified-with: playwright
---


## Platform Support Status (Current)

| Platform | Current Support | Requirements |
|---|---|---|
| Claude | Native MCP integration | Register in `mcpServers` |
| Codex | MCP script integration | `scripts/mcp-setup.sh --codex` or equivalent config |
| Gemini | MCP registration | `mcpServers`/bridge configuration |
| OpenCode | MCP/bridge integration | `omx`/`ohmg` or equivalent setup |

Whether this skill alone is sufficient:
- Claude/Gemini: **Yes**
- Codex: **Yes (requires script-based setup)**
- OpenCode: **Yes (via orchestration)**

# Vibe Kanban — AI Agent Kanban Board

> Manage multiple AI agents (Claude/Codex/Gemini) from a single Kanban board.
> Moving a card (task) to In Progress automatically creates a git worktree and starts the agent.

## When to use this skill

- When breaking an epic into independent tasks for parallel agent assignment
- When you want to visually track the status of ongoing AI work
- When you want to review agent results as diffs/logs in the UI and retry them
- When combining GitHub PR-based team collaboration with AI agent work

---

## Prerequisites

```bash
# Node.js 18+ required
node --version

# Complete agent authentication beforehand
claude --version    # Set ANTHROPIC_API_KEY
codex --version     # Set OPENAI_API_KEY (optional)
gemini --version    # Set GOOGLE_API_KEY (optional)
opencode --version  # No separate setup needed (GUI-based)
```

> **Verified versions (as of 2026-02-22)**
> - vibe-kanban: v0.1.17
> - claude (Claude Code): 2.1.50
> - codex: 0.104.0
> - gemini: 0.29.5
> - opencode: 1.2.10

---

## Installation & Running

### npx (fastest)

```bash
# Run immediately (no installation needed)
npx vibe-kanban

# Specify port (default port 3000)
npx vibe-kanban --port 3001

# Specify port and environment variable together
PORT=3001 npx vibe-kanban --port 3001

# Use wrapper script
bash scripts/vibe-kanban-start.sh
```

Browser opens `http://localhost:3000` automatically.

> ⚠️ **Port conflict warning**: If another dev server like Next.js is using port 3000,
> run `PORT=3001 npx vibe-kanban --port 3001`.
> Confirm `Main server on :3001` in the startup log, then visit `http://localhost:3001`.

Normal startup log:
```
Starting vibe-kanban v0.1.17...
No user profiles.json found, using defaults only
Starting PR monitoring service with interval 60s
Remote client initialized with URL: https://api.vibekanban.com
Main server on :3001, Preview proxy on :XXXXX
Opening browser...
```

### Clone + dev mode

```bash
git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban
pnpm i
pnpm run dev
```

---

## Environment Variables

| Variable | Description | Default |
|------|------|--------|
| `PORT` | Server port | `3000` |
| `HOST` | Server host | `127.0.0.1` |
| `VIBE_KANBAN_REMOTE` | Allow remote connections | `false` |
| `VK_ALLOWED_ORIGINS` | CORS allowed origins | Not set |
| `DISABLE_WORKTREE_CLEANUP` | Disable worktree cleanup | Not set |
| `ANTHROPIC_API_KEY` | For Claude Code agent | — |
| `OPENAI_API_KEY` | For Codex/GPT agent | — |
| `GOOGLE_API_KEY` | For Gemini agent | — |

Set in `.env` file before starting the server.

> **API key location per agent (Settings → Agents → Environment variables)**
> - Claude Code: `ANTHROPIC_API_KEY`
> - Codex: `OPENAI_API_KEY`
> - Gemini: `GOOGLE_API_KEY`
> - Opencode: No separate setup needed (built-in auth)

---

## MCP Configuration

Vibe Kanban runs as an MCP (Model Context Protocol) server, letting agents control the board directly.

### Claude Code MCP Setup

`~/.claude/settings.json` or project `.mcp.json`:

```json
{
  "mcpServers": {
    "vibe-kanban": {
      "command": "npx",
      "args": ["vibe-kanban", "--mcp"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "3001"
      }
    }
  }
}
```

### OpenCode MCP Setup

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "vibe-kanban": {
      "command": "npx",
      "args": ["vibe-kanban", "--mcp"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "3001"
      }
    }
  }
}
```

After restarting, `vk_*` tools are available directly in your OpenCode session.


### MCP Tool List

| Tool | Description |
|------|------|
| `vk_list_cards` | List all cards (workspaces) |
| `vk_create_card` | Create a new card |
| `vk_move_card` | Change card status |
| `vk_get_diff` | Get card diff |
| `vk_retry_card` | Re-run a card |

> ⚠️ **Tool name changes from older versions**: `vk_list_tasks` → `vk_list_cards`, `vk_create_task` → `vk_create_card`
> These are the confirmed tool names from the actual MCP API as of v0.1.17.

### Codex MCP Integration

To connect Vibe Kanban with Codex, run the following from your project root:

```bash
bash scripts/mcp-setup.sh --codex
```

This command adds the `vibe-kanban` MCP server config to `~/.codex/config.toml`.  
Hook-based auto-looping is not default Codex behavior, so retry/loop management is handled via board card progress states or a higher-level orchestrator.

---

## Workspace → Parallel Agents → PR Workflow

> **v0.1.17 actual UI structure**: Vibe Kanban is a Kanban board, but
> the actual unit of work is a **Workspace**.
> Each workspace handles one task independently.

### 1. Start the server

```bash
# Default run
npx vibe-kanban
# → http://localhost:3000

# Port conflict (e.g., Next.js)
PORT=3001 npx vibe-kanban --port 3001
# → http://localhost:3001
```

### 2. (Optional) Review epic plan with planno

```text
Review the implementation plan for this feature with planno
```

planno (plannotator) is an independent skill — usable without Vibe Kanban.

### 3. Create a Workspace

1. Open the UI → click **"+ Create Workspace"** or the `+` button in the left sidebar
2. **Which repositories?** screen:
   - **Browse** → select a git repo from the filesystem (manual path entry supported)
   - **Recent** → previously used repos
   - Select a repo, then choose a branch (default: `main`)
   - Click **Continue**
3. **What would you like to work on?** screen:
   - Select an agent (Opencode, Claude Code, Codex, Gemini, Amp, Qwen Code, Copilot, Droid, Cursor Agent)
   - Enter a task description (Markdown supported)
   - Select a mode (Default, Build, etc.)
   - Click **Create**

### 4. Automatic agent execution

When a workspace is created:
- A `vk/<hash>-<slug>` branch is created automatically (e.g., `vk/3816-add-a-comment-to`)
- A git worktree is created automatically (fully isolated per agent)
- The selected agent CLI runs with log streaming

Workspace states:
- **Running**: Agent is executing (left sidebar)
- **Idle**: Waiting
- **Needs Attention**: Agent finished or needs input

### 5. Review results

- **Changes panel**: View file diffs
- **Logs panel**: Agent execution logs
- **Preview panel**: Web app preview
- **Terminal**: Run commands directly
- **Notes**: Write notes

### 6. Create PR & finish

- Workspace detail → **"Open pull request"** button
- PR merge → workspace moves to Archive
- Worktree cleaned up automatically

---

## Git Worktree Isolation Structure

Workspace directory (configurable in Settings → General → Workspace Directory):
```
~/.vibe-kanban-workspaces/          ← default location (under home directory)
├── <workspace-uuid-1>/             ← workspace 1 isolated environment
├── <workspace-uuid-2>/             ← workspace 2 isolated environment
└── <workspace-uuid-3>/             ← workspace 3 isolated environment
```

Branch naming (configurable in Settings → General → Git → Branch Prefix):
```
vk/<4-char ID>-<task-slug>
e.g.: vk/3816-add-a-comment-to-readme
```

Internal behavior:
```bash
git worktree add <workspace-dir> -b vk/<hash>-<task-slug> main
<agent-cli> -p "<task-description>" --cwd <workspace-dir>
```

> **Recommended .gitignore entries:**
> ```
> .vibe-kanban-workspaces/
> .vibe-kanban/
> ```

---

## Remote Deployment

### Docker

```bash
# Official image
docker run -p 3000:3000 vibekanban/vibe-kanban

# Pass environment variables
docker run -p 3000:3000 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e VK_ALLOWED_ORIGINS=https://vk.example.com \
  vibekanban/vibe-kanban
```

### Reverse Proxy (Nginx/Caddy)

```bash
# CORS must be allowed
VK_ALLOWED_ORIGINS=https://vk.example.com

# Or multiple origins
VK_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com
```

### SSH Remote Access

Integrates with VSCode Remote-SSH:
```
vscode://vscode-remote/ssh-remote+user@host/path/to/.vk/trees/<task-slug>
```

---

## Troubleshooting

### Worktree conflicts / orphaned worktrees

```bash
# Clean up orphaned worktrees
git worktree prune

# List current worktrees
git worktree list

# Force remove a specific worktree
git worktree remove .vk/trees/<slug> --force
```

### 403 Forbidden (CORS error)

```bash
# CORS config required for remote access
VK_ALLOWED_ORIGINS=https://your-domain.com npx vibe-kanban
```

### Agent won't start

```bash
# Test CLI directly
claude --version
codex --version

# Check API keys
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
```

### Port conflict

```bash
# Use a different port
npx vibe-kanban --port 3001

# Or use environment variable
PORT=3001 npx vibe-kanban
```

### SQLite lock error

```bash
# Disable worktree cleanup and restart
DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban
```

---

## UI vs CLI Decision Guide

| Situation | Mode |
|------|------|
| Shared team board, visual progress tracking | UI (`npx vibe-kanban`) |
| CI/CD pipeline, script automation | CLI (`scripts/pipeline.sh`) |
| Quick local experiments | CLI (`scripts/conductor.sh`) |
| Browser diff/log review | UI |

---

## Supported Agents (verified v0.1.17)

Configure each agent in Settings → Agents:

| Agent | Command | API Key |
|----------|------|--------|
| **Opencode** | `opencode` | Built-in (default) |
| **Claude Code** | `claude` | `ANTHROPIC_API_KEY` |
| **Codex** | `codex` | `OPENAI_API_KEY` |
| **Gemini** | `gemini` | `GOOGLE_API_KEY` |
| **Amp** | `amp` | Separate |
| **Qwen Code** | `qwen-coder` | Separate |
| **Copilot** | `copilot` | GitHub account |
| **Droid** | `droid` | Separate |
| **Cursor Agent** | `cursor` | Cursor subscription |

Configurable per agent:
- **Append prompt**: Additional instructions appended at agent runtime
- **Model**: Model name to use (e.g., `claude-opus-4-6`)
- **Variant**: Model variant
- **Auto Approve**: Auto-approve agent actions (default: ON)
- **Auto Compact**: Auto-compress context (default: ON)
- **Environment variables**: API keys and other env vars

## Representative Use Cases

### 1. Parallel epic decomposition

```
"Payment Flow v2" epic
  ├── Workspace 1: Frontend UI  → Claude Code
  ├── Workspace 2: Backend API  → Codex
  └── Workspace 3: Integration tests → Opencode
→ 3 workspaces Running simultaneously → parallel implementation
```

### 2. Role-based specialist agent assignment

```
Claude Code  → design/domain-heavy features
Codex        → types/tests/refactoring
Gemini       → docs/storybook writing
Opencode     → general tasks (default)
```

### 3. GitHub PR-based team collaboration

```
Set VIBE_KANBAN_REMOTE=true
→ Team members check status on the board
→ Review/approval only via GitHub PR
→ Parallel agents + traditional PR process combined
```

### 4. Implementation comparison

```
Same task, two workspaces:
  Workspace A → Claude Code (UI structure focus)
  Workspace B → Codex (performance optimization focus)
→ Compare PRs, pick best-of-both
```

### 5. OpenCode + ulw parallel delegation

Combine with OpenCode's ulw (ultrawork) mode to run agents in parallel at the epic level:

```python
# ulw keyword → activates ultrawork parallel execution layer
# Vibe Kanban board: npx vibe-kanban (run in a separate terminal)

task(category="visual-engineering", run_in_background=True,
     load_skills=["frontend-ui-ux", "vibe-kanban"],
     description="[Kanban WS1] Frontend UI",
     prompt="Implement payment flow UI — card input, order confirmation, and completion screens in src/components/payment/")

task(category="unspecified-high", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[Kanban WS2] Backend API",
     prompt="Implement payment flow API — POST /charge, POST /refund, GET /status/:id")

task(category="unspecified-low", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[Kanban WS3] Integration tests",
     prompt="Write payment E2E tests — success/failure/refund scenarios")

# → 3 workspaces appear simultaneously in Running state on the Kanban board
# → On each completion: Needs Attention → PR created → Archive
```

---

## Tips

- Keep card scope narrow (1 card = 1 commit unit)
- For changes spanning 2+ files, review the plan with planno first
- Use `VIBE_KANBAN_REMOTE=true` only on trusted networks
- If an agent stalls, reassign or split the card

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                    Vibe Kanban UI                       │
│   ┌──────────┬──────────┬──────────┬──────────┐        │
│   │  To Do   │In Progress│  Review  │   Done   │        │
│   └──────────┴──────────┴──────────┴──────────┘        │
└───────────────────────────┬─────────────────────────────┘
                            │ REST API
┌───────────────────────────▼─────────────────────────────┐
│                    Rust Backend                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │
│  │ server  │  │executors │  │   git   │  │ services │  │
│  └─────────┘  └──────────┘  └─────────┘  └──────────┘  │
│                   │                                     │
│             ┌─────▼─────┐                               │
│             │  SQLite   │                               │
│             └───────────┘                               │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
   ┌────▼────┐        ┌─────▼─────┐       ┌────▼────┐
   │ Claude  │        │   Codex   │       │ Gemini  │
   │worktree1│        │ worktree2 │       │worktree3│
   └─────────┘        └───────────┘       └─────────┘
```

---

## References

- [GitHub repo: BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban)
- [Official landing page: vibekanban.com](https://vibekanban.online)
- [Architecture analysis: vibe-kanban – a Kanban board for AI agents](https://virtuslab.com/blog/ai/vibe-kanban/)
- [Adoption story](https://bluedreamer-twenty.tistory.com/7)
- [Demo: Run Multiple Claude Code Agents Without Git Conflicts](https://www.youtube.com/watch?v=W45XJWZiwPM)
- [Demo: Claude Code Just Got Way Better | Auto Claude Kanban Boards](https://www.youtube.com/watch?v=vPPAhTYoCdA)

---

## Skill File Structure

```
.agent-skills/vibe-kanban/
├── SKILL.md              # Main skill document
├── SKILL.toon            # TOON format (compressed)
├── scripts/
│   ├── start.sh          # Server start wrapper
│   ├── cleanup.sh        # Worktree cleanup
│   ├── mcp-setup.sh      # MCP setup automation
│   └── health-check.sh   # Server health check
├── references/
│   ├── environment-variables.md  # Environment variable reference
│   └── mcp-api.md                # MCP API reference
└── templates/
    ├── claude-mcp-config.json    # Claude Code MCP config
    ├── docker-compose.yml        # Docker deployment template
    └── .env.example              # Environment variable example
```

### Script Usage

```bash
# Start server
bash scripts/start.sh --port 3001

# Worktree cleanup
bash scripts/cleanup.sh --dry-run  # Preview
bash scripts/cleanup.sh --all       # Remove all VK worktrees

# MCP setup
bash scripts/mcp-setup.sh --claude  # Claude Code setup
bash scripts/mcp-setup.sh --all     # Setup for all agents

# Health check
bash scripts/health-check.sh
bash scripts/health-check.sh --json  # JSON output
```

---

## Quick Reference

```
=== Start server ===
npx vibe-kanban                       Run immediately (port 3000)
PORT=3001 npx vibe-kanban --port 3001 Port conflict (e.g., Next.js)
http://localhost:3000                  Board UI

=== Environment variables ===
PORT=3001                        Change port
VK_ALLOWED_ORIGINS=https://...   Allow CORS
ANTHROPIC_API_KEY=...            Claude Code auth
OPENAI_API_KEY=...               Codex auth
GOOGLE_API_KEY=...               Gemini auth

=== MCP integration ===
npx vibe-kanban --mcp            MCP mode
vk_list_cards                    List cards (workspaces)
vk_create_card                   Create card
vk_move_card                     Change status

=== Workspace flow ===
Create → Running → Needs Attention → Archive
Running: worktree created + agent started
Needs Attention: finished or needs input
Archive: PR merge complete

=== MCP config file locations ===
Opencode: ~/.config/opencode/opencode.json
Claude Code: ~/.claude/settings.json or .mcp.json

=== worktree cleanup ===
git worktree prune               Clean up orphans
git worktree list                List all
git worktree remove <path>       Force remove
```


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/mcp-setup.sh

```bash
#!/usr/bin/env bash
# mcp-setup.sh — Vibe Kanban MCP 서버 설정 스크립트
# 사용법: bash mcp-setup.sh [--claude|--codex|--all]
#
# 예시:
#   bash mcp-setup.sh --claude   # Claude Code 설정만
#   bash mcp-setup.sh --codex    # Codex CLI 설정만
#   bash mcp-setup.sh --all      # 모든 에이전트 설정

set -euo pipefail

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
info()  { echo -e "${BLUE}ℹ️  $*${NC}"; }
ok()    { echo -e "${GREEN}✅ $*${NC}"; }
warn()  { echo -e "${YELLOW}⚠️  $*${NC}"; }
error() { echo -e "${RED}❌ $*${NC}" >&2; }

# ─── 인자 파싱 ───────────────────────────────────────────────────────────────
SETUP_CLAUDE=false
SETUP_CODEX=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --claude) SETUP_CLAUDE=true; shift ;;
    --codex)  SETUP_CODEX=true; shift ;;
    --all)    SETUP_CLAUDE=true; SETUP_CODEX=true; shift ;;
    *) shift ;;
  esac
done

# 기본값: 모두 설정
if [[ "$SETUP_CLAUDE" == "false" && "$SETUP_CODEX" == "false" ]]; then
  SETUP_CLAUDE=true
  SETUP_CODEX=true
fi

echo "╔══════════════════════════════════════╗"
echo "║  Vibe Kanban MCP 설정                ║"
echo "╚══════════════════════════════════════╝"
echo ""

# ─── MCP 설정 JSON 생성 ──────────────────────────────────────────────────────
MCP_CONFIG=$(cat <<'EOF'
{
  "vibe-kanban": {
    "command": "npx",
    "args": ["vibe-kanban", "--mcp"],
    "env": {
      "MCP_HOST": "127.0.0.1",
      "MCP_PORT": "3001"
    }
  }
}
EOF
)

# ─── Claude Code 설정 ────────────────────────────────────────────────────────
if [[ "$SETUP_CLAUDE" == "true" ]]; then
  info "Claude Code MCP 설정 중..."
  
  CLAUDE_CONFIG="$HOME/.claude/claude_desktop_config.json"
  CLAUDE_DIR="$HOME/.claude"
  
  # 디렉토리 생성
  mkdir -p "$CLAUDE_DIR"
  
  if [[ -f "$CLAUDE_CONFIG" ]]; then
    # 기존 설정에 병합
    if command -v jq &>/dev/null; then
      EXISTING=$(cat "$CLAUDE_CONFIG")
      MERGED=$(echo "$EXISTING" | jq --argjson vk "$MCP_CONFIG" '.mcpServers += $vk')
      echo "$MERGED" > "$CLAUDE_CONFIG"
      ok "Claude Code: 기존 설정에 병합됨"
    else
      warn "jq가 없어 수동 병합이 필요합니다."
      echo "다음 내용을 $CLAUDE_CONFIG의 mcpServers에 추가하세요:"
      echo "$MCP_CONFIG"
    fi
  else
    # 새 설정 파일 생성
    cat > "$CLAUDE_CONFIG" <<EOF
{
  "mcpServers": $MCP_CONFIG
}
EOF
    ok "Claude Code: 새 설정 파일 생성됨"
  fi
  
  echo "  설정 파일: $CLAUDE_CONFIG"
  echo ""
fi

# ─── Codex CLI 설정 ──────────────────────────────────────────────────────────
if [[ "$SETUP_CODEX" == "true" ]]; then
  info "Codex CLI MCP 설정 중..."
  
  CODEX_CONFIG="$HOME/.codex/config.toml"
  CODEX_DIR="$HOME/.codex"
  
  # 디렉토리 생성
  mkdir -p "$CODEX_DIR"
  
  # TOML 형식으로 변환
  CODEX_MCP_CONFIG=$(cat <<'EOF'

# Vibe Kanban MCP Server
[[mcp_servers]]
name = "vibe-kanban"
command = "npx"
args = ["vibe-kanban", "--mcp"]

[mcp_servers.env]
MCP_HOST = "127.0.0.1"
MCP_PORT = "3001"
EOF
)

  if [[ -f "$CODEX_CONFIG" ]]; then
    # 기존 설정에 추가
    if ! grep -q "vibe-kanban" "$CODEX_CONFIG"; then
      echo "$CODEX_MCP_CONFIG" >> "$CODEX_CONFIG"
      ok "Codex CLI: 기존 설정에 추가됨"
    else
      warn "Codex CLI: 이미 vibe-kanban 설정이 존재합니다."
    fi
  else
    # 새 설정 파일 생성
    cat > "$CODEX_CONFIG" <<EOF
# Codex CLI Configuration
$CODEX_MCP_CONFIG
EOF
    ok "Codex CLI: 새 설정 파일 생성됨"
  fi
  
  echo "  설정 파일: $CODEX_CONFIG"
  echo ""
fi

# ─── 완료 ────────────────────────────────────────────────────────────────────
ok "MCP 설정 완료!"
echo ""
echo "다음 단계:"
echo "  1. 에이전트를 재시작하세요"
echo "  2. 'npx vibe-kanban --mcp'로 MCP 서버 시작"
echo "  3. 에이전트에서 vibe-kanban MCP 도구 사용 가능"
echo ""
echo "MCP 도구 목록:"
echo "  - vk_list_cards: 카드 목록 조회"
echo "  - vk_create_card: 새 카드 생성"
echo "  - vk_move_card: 카드 이동"
echo "  - vk_get_logs: 에이전트 로그 조회"

```

### scripts/start.sh

```bash
#!/usr/bin/env bash
# vibe-kanban-start.sh — Vibe Kanban 서버 시작 래퍼
# 사용법: bash scripts/vibe-kanban-start.sh [--port 3000] [--remote]
#
# 예시:
#   bash scripts/vibe-kanban-start.sh
#   bash scripts/vibe-kanban-start.sh --port 3001
#   bash scripts/vibe-kanban-start.sh --remote

set -euo pipefail

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
info()  { echo -e "${BLUE}ℹ️  $*${NC}"; }
ok()    { echo -e "${GREEN}✅ $*${NC}"; }
warn()  { echo -e "${YELLOW}⚠️  $*${NC}"; }
error() { echo -e "${RED}❌ $*${NC}" >&2; }

# ─── 인자 파싱 ───────────────────────────────────────────────────────────────
PORT="${VIBE_KANBAN_PORT:-3000}"
REMOTE="${VIBE_KANBAN_REMOTE:-false}"
OPEN_BROWSER=true

while [[ $# -gt 0 ]]; do
  case "$1" in
    --port)   PORT="$2"; shift 2 ;;
    --remote) REMOTE=true; shift ;;
    --no-open) OPEN_BROWSER=false; shift ;;
    *) shift ;;
  esac
done

echo "╔══════════════════════════════════════╗"
echo "║  Vibe Kanban 시작                     ║"
echo "╚══════════════════════════════════════╝"
echo ""

# ─── Node.js 확인 ────────────────────────────────────────────────────────────
if ! command -v node &>/dev/null; then
  error "Node.js가 필요합니다. https://nodejs.org 에서 설치하세요."
  exit 1
fi

NODE_MAJOR=$(node --version | sed 's/v//' | cut -d. -f1)
if [[ $NODE_MAJOR -lt 18 ]]; then
  error "Node.js 18+ 필요 (현재: $(node --version))"
  exit 1
fi
ok "Node.js: $(node --version)"

# ─── npx 확인 ────────────────────────────────────────────────────────────────
if ! command -v npx &>/dev/null; then
  error "npx가 필요합니다 (Node.js와 함께 설치됩니다)"
  exit 1
fi

# ─── 에이전트 인증 확인 ──────────────────────────────────────────────────────
echo ""
info "에이전트 인증 상태 확인..."

if [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
  ok "ANTHROPIC_API_KEY: 설정됨 (Claude 사용 가능)"
else
  warn "ANTHROPIC_API_KEY: 미설정 (Claude 에이전트 사용 불가)"
fi

if [[ -n "${OPENAI_API_KEY:-}" ]]; then
  ok "OPENAI_API_KEY: 설정됨 (Codex/GPT 사용 가능)"
else
  warn "OPENAI_API_KEY: 미설정 (Codex 에이전트 사용 불가)"
fi

echo ""

# ─── 환경 변수 설정 ──────────────────────────────────────────────────────────
export VIBE_KANBAN_PORT="$PORT"
export VIBE_KANBAN_REMOTE="$REMOTE"

# .env 파일 로드 (존재하는 경우)
if [[ -f ".env" ]]; then
  info ".env 파일 로드 중..."
  set -a
  source .env
  set +a
fi

# ─── 실행 정보 ───────────────────────────────────────────────────────────────
echo "설정:"
echo "  포트   : $PORT"
echo "  원격   : $REMOTE"
echo "  URL    : http://localhost:$PORT"
if [[ "$REMOTE" == "true" ]]; then
  warn "원격 연결 허용됨. 신뢰할 수 있는 네트워크에서만 사용하세요."
fi
echo ""

# ─── 브라우저 자동 오픈 (백그라운드) ────────────────────────────────────────
if [[ "$OPEN_BROWSER" == "true" ]]; then
  (
    sleep 3
    if command -v open &>/dev/null; then
      open "http://localhost:$PORT" 2>/dev/null || true
    elif command -v xdg-open &>/dev/null; then
      xdg-open "http://localhost:$PORT" 2>/dev/null || true
    fi
  ) &
fi

# ─── vibe-kanban 실행 ────────────────────────────────────────────────────────
info "Vibe Kanban 시작 중 (npx vibe-kanban)..."
echo "종료하려면 Ctrl+C"
echo ""

exec npx vibe-kanban

```

### scripts/cleanup.sh

```bash
#!/usr/bin/env bash
# cleanup.sh — Vibe Kanban worktree 정리 스크립트
# 사용법: bash cleanup.sh [--all] [--dry-run]
#
# 예시:
#   bash cleanup.sh              # 병합된 worktree만 정리
#   bash cleanup.sh --all        # 모든 vibe-kanban worktree 정리
#   bash cleanup.sh --dry-run    # 정리할 항목만 표시 (실제 삭제 안함)

set -euo pipefail

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
info()  { echo -e "${BLUE}ℹ️  $*${NC}"; }
ok()    { echo -e "${GREEN}✅ $*${NC}"; }
warn()  { echo -e "${YELLOW}⚠️  $*${NC}"; }
error() { echo -e "${RED}❌ $*${NC}" >&2; }

# ─── 인자 파싱 ───────────────────────────────────────────────────────────────
CLEAN_ALL=false
DRY_RUN=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --all)     CLEAN_ALL=true; shift ;;
    --dry-run) DRY_RUN=true; shift ;;
    *) shift ;;
  esac
done

echo "╔══════════════════════════════════════╗"
echo "║  Vibe Kanban Worktree 정리           ║"
echo "╚══════════════════════════════════════╝"
echo ""

# ─── Git 저장소 확인 ─────────────────────────────────────────────────────────
if ! git rev-parse --git-dir &>/dev/null; then
  error "Git 저장소가 아닙니다."
  exit 1
fi

# ─── Worktree 목록 조회 ──────────────────────────────────────────────────────
info "현재 worktree 목록:"
git worktree list
echo ""

# ─── 정리 대상 식별 ──────────────────────────────────────────────────────────
WORKTREES=$(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2-)
VK_WORKTREES=()

while IFS= read -r wt; do
  if [[ "$wt" == *"vk-"* ]] || [[ "$wt" == *"vibe-kanban-"* ]]; then
    VK_WORKTREES+=("$wt")
  fi
done <<< "$WORKTREES"

if [[ ${#VK_WORKTREES[@]} -eq 0 ]]; then
  ok "정리할 Vibe Kanban worktree가 없습니다."
  exit 0
fi

info "Vibe Kanban worktree 발견: ${#VK_WORKTREES[@]}개"
for wt in "${VK_WORKTREES[@]}"; do
  echo "  - $wt"
done
echo ""

# ─── 정리 실행 ───────────────────────────────────────────────────────────────
CLEANED=0

for wt in "${VK_WORKTREES[@]}"; do
  # 브랜치명 추출
  BRANCH=$(git worktree list | grep "$wt" | awk '{print $3}' | tr -d '[]')
  
  # 병합 여부 확인 (--all이 아닌 경우)
  if [[ "$CLEAN_ALL" == "false" ]]; then
    if ! git branch --merged main 2>/dev/null | grep -q "$BRANCH"; then
      warn "스킵: $wt (병합되지 않음)"
      continue
    fi
  fi
  
  if [[ "$DRY_RUN" == "true" ]]; then
    info "[DRY-RUN] 삭제 예정: $wt"
  else
    info "정리 중: $wt"
    git worktree remove "$wt" --force 2>/dev/null || true
    git branch -D "$BRANCH" 2>/dev/null || true
    ((CLEANED++))
  fi
done

echo ""

# ─── Worktree prune ──────────────────────────────────────────────────────────
if [[ "$DRY_RUN" == "false" ]]; then
  info "git worktree prune 실행..."
  git worktree prune
fi

# ─── 결과 출력 ───────────────────────────────────────────────────────────────
if [[ "$DRY_RUN" == "true" ]]; then
  info "DRY-RUN 모드: 실제 삭제 없음"
else
  ok "정리 완료: ${CLEANED}개 worktree 삭제됨"
fi

echo ""
info "현재 worktree 목록:"
git worktree list

```

### scripts/health-check.sh

```bash
#!/usr/bin/env bash
# health-check.sh — Vibe Kanban 서버 상태 확인 스크립트
# 사용법: bash health-check.sh [--port 3000] [--json]
#
# 예시:
#   bash health-check.sh
#   bash health-check.sh --port 3001
#   bash health-check.sh --json

set -euo pipefail

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
info()  { echo -e "${BLUE}ℹ️  $*${NC}"; }
ok()    { echo -e "${GREEN}✅ $*${NC}"; }
warn()  { echo -e "${YELLOW}⚠️  $*${NC}"; }
error() { echo -e "${RED}❌ $*${NC}" >&2; }

# ─── 인자 파싱 ───────────────────────────────────────────────────────────────
PORT="${VIBE_KANBAN_PORT:-3000}"
JSON_OUTPUT=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --port) PORT="$2"; shift 2 ;;
    --json) JSON_OUTPUT=true; shift ;;
    *) shift ;;
  esac
done

BASE_URL="http://localhost:$PORT"

# ─── JSON 출력 모드 ──────────────────────────────────────────────────────────
if [[ "$JSON_OUTPUT" == "true" ]]; then
  RESULT='{}'
  
  # 서버 상태
  if curl -s "$BASE_URL/api/health" &>/dev/null; then
    RESULT=$(echo "$RESULT" | jq '. + {"server": "running", "port": '"$PORT"'}')
  else
    RESULT=$(echo "$RESULT" | jq '. + {"server": "stopped", "port": '"$PORT"'}')
    echo "$RESULT"
    exit 1
  fi
  
  # 카드 수
  CARDS=$(curl -s "$BASE_URL/api/cards" 2>/dev/null | jq 'length' 2>/dev/null || echo "0")
  RESULT=$(echo "$RESULT" | jq '. + {"cards": '"$CARDS"'}')
  
  # Worktree 수
  if git rev-parse --git-dir &>/dev/null; then
    WT_COUNT=$(git worktree list | wc -l | tr -d ' ')
    RESULT=$(echo "$RESULT" | jq '. + {"worktrees": '"$WT_COUNT"'}')
  fi
  
  echo "$RESULT"
  exit 0
fi

# ─── 일반 출력 모드 ──────────────────────────────────────────────────────────
echo "╔══════════════════════════════════════╗"
echo "║  Vibe Kanban 상태 확인               ║"
echo "╚══════════════════════════════════════╝"
echo ""

# 서버 상태
info "서버 상태 확인: $BASE_URL"
if curl -s --connect-timeout 2 "$BASE_URL/api/health" &>/dev/null; then
  ok "서버: 실행 중 (포트 $PORT)"
else
  error "서버: 응답 없음"
  echo ""
  echo "서버를 시작하려면:"
  echo "  npx vibe-kanban"
  echo "  또는"
  echo "  bash scripts/start.sh"
  exit 1
fi

# 카드 상태
echo ""
info "카드 상태:"
CARDS_JSON=$(curl -s "$BASE_URL/api/cards" 2>/dev/null || echo "[]")

if command -v jq &>/dev/null; then
  TODO=$(echo "$CARDS_JSON" | jq '[.[] | select(.column == "todo")] | length')
  IN_PROGRESS=$(echo "$CARDS_JSON" | jq '[.[] | select(.column == "in_progress")] | length')
  REVIEW=$(echo "$CARDS_JSON" | jq '[.[] | select(.column == "review")] | length')
  DONE=$(echo "$CARDS_JSON" | jq '[.[] | select(.column == "done")] | length')
  
  echo "  To Do:       $TODO"
  echo "  In Progress: $IN_PROGRESS"
  echo "  Review:      $REVIEW"
  echo "  Done:        $DONE"
else
  TOTAL=$(echo "$CARDS_JSON" | grep -o '"id"' | wc -l | tr -d ' ')
  echo "  총 카드 수: $TOTAL"
fi

# Git worktree 상태
echo ""
info "Git Worktree 상태:"
if git rev-parse --git-dir &>/dev/null; then
  git worktree list | while read -r line; do
    if [[ "$line" == *"vk-"* ]] || [[ "$line" == *"vibe-kanban-"* ]]; then
      echo "  [VK] $line"
    fi
  done
  
  VK_COUNT=$(git worktree list | grep -E "(vk-|vibe-kanban-)" | wc -l | tr -d ' ')
  if [[ "$VK_COUNT" -eq 0 ]]; then
    echo "  Vibe Kanban worktree 없음"
  else
    echo "  총 VK worktree: $VK_COUNT"
  fi
else
  warn "Git 저장소가 아닙니다."
fi

# MCP 상태
echo ""
info "MCP 상태:"
MCP_PORT="${MCP_PORT:-3001}"
if curl -s --connect-timeout 2 "http://localhost:$MCP_PORT" &>/dev/null; then
  ok "MCP 서버: 실행 중 (포트 $MCP_PORT)"
else
  echo "  MCP 서버: 실행 안함"
  echo "  시작하려면: npx vibe-kanban --mcp"
fi

echo ""
ok "상태 확인 완료"

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### references/environment-variables.md

```markdown
# Vibe Kanban 환경 변수 레퍼런스

## 서버 설정

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `PORT` | `3000` | 웹 서버 포트 |
| `VIBE_KANBAN_PORT` | `3000` | 웹 서버 포트 (별칭) |
| `VIBE_KANBAN_REMOTE` | `false` | 원격 연결 허용 (`true`/`false`) |
| `VIBE_KANBAN_DATA_DIR` | `.vibe-kanban` | 데이터 저장 디렉토리 |

## MCP 설정

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `MCP_HOST` | `127.0.0.1` | MCP 서버 바인딩 주소 |
| `MCP_PORT` | `3001` | MCP 서버 포트 |

## CORS 설정

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `VK_ALLOWED_ORIGINS` | `http://localhost:*` | 허용된 CORS 오리진 (쉼표 구분) |

## 에이전트 설정

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `ANTHROPIC_API_KEY` | - | Claude 에이전트용 API 키 |
| `OPENAI_API_KEY` | - | Codex/GPT 에이전트용 API 키 |
| `GOOGLE_API_KEY` | - | Gemini 에이전트용 API 키 |

## Git 설정

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `GITHUB_TOKEN` | - | GitHub PR 자동 생성용 토큰 |
| `GIT_WORKTREE_BASE` | `.worktrees` | Worktree 저장 디렉토리 |

## 예시: .env 파일

```bash
PORT=3000
VIBE_KANBAN_REMOTE=false
VK_ALLOWED_ORIGINS=http://localhost:3000,https://vk.example.com
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...
```

## 예시: Docker 환경

```bash
docker run -p 3000:3000 \
  -e VIBE_KANBAN_REMOTE=true \
  -e VK_ALLOWED_ORIGINS=https://vk.example.com \
  vibekanban/vibe-kanban
```

```

### references/mcp-api.md

```markdown
# Vibe Kanban MCP API 레퍼런스

> **검증 버전**: v0.1.17 (2026-02-22 Playwright 검증)
> MCP를 통해 에이전트가 직접 Vibe Kanban 워크스페이스를 생성하고 관리할 수 있습니다.

## 개요

Vibe Kanban MCP 서버는 표준 MCP 프로토콜을 통해 보드 조작 API를 제공합니다.

## 도구 목록

### vk_list_cards

카드 목록을 조회합니다.

**파라미터:**
| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `column` | string | 아니오 | 필터링할 칼럼 (`todo`, `in_progress`, `review`, `done`) |

**응답:**
```json
[
  {
    "id": "card_abc123",
    "title": "API 엔드포인트 구현",
    "description": "GET /api/users 엔드포인트 추가",
    "column": "in_progress",
    "agent": "claude",
    "worktree": "~/.vibe-kanban-workspaces/<workspace-uuid>",
    "created_at": "2026-02-21T10:00:00Z"
  }
]
```

### vk_create_card

새 카드를 생성합니다.

**파라미터:**
| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `title` | string | 예 | 카드 제목 |
| `description` | string | 아니오 | 카드 설명 |
| `agent` | string | 아니오 | 에이전트 타입 (`opencode`, `claude`, `codex`, `gemini`, `amp`, `qwen`, `copilot`, `droid`, `cursor`) |

**응답:**
```json
{
  "id": "card_xyz789",
  "title": "새 카드",
  "column": "todo",
  "created_at": "2026-02-21T10:30:00Z"
}
```

### vk_move_card

카드를 다른 칼럼으로 이동합니다.

**파라미터:**
| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `card_id` | string | 예 | 카드 ID |
| `column` | string | 예 | 목표 칼럼 (`todo`, `in_progress`, `review`, `done`) |

**응답:**
```json
{
  "id": "card_abc123",
  "column": "review",
  "worktree": "~/.vibe-kanban-workspaces/<workspace-uuid>"
}
```

**부작용:**
- 카드 생성 → Running: Git worktree + 브랜치(`vk/<4자ID>-<slug>`) 자동 생성 + 에이전트 실행
- Done/Archive: Draft PR 생성 (GitHub 연결 시)

### vk_get_logs

에이전트 실행 로그를 조회합니다.

**파라미터:**
| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `card_id` | string | 예 | 카드 ID |
| `tail` | number | 아니오 | 마지막 N줄만 (기본: 100) |

**응답:**
```json
{
  "card_id": "card_abc123",
  "logs": "Cloning worktree...\nRunning claude...\n✅ Task completed",
  "exit_code": 0,
  "duration_ms": 45000
}
```

### vk_retry_card

실패한 카드를 재시도합니다.

**파라미터:**
| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `card_id` | string | 예 | 카드 ID |
| `clear_worktree` | boolean | 아니오 | Worktree 초기화 여부 (기본: false) |

**응답:**
```json
{
  "id": "card_abc123",
  "column": "in_progress",
  "retry_count": 2
}
```

## 에러 코드

| 코드 | 설명 |
|------|------|
| `CARD_NOT_FOUND` | 카드를 찾을 수 없음 |
| `INVALID_COLUMN` | 잘못된 칼럼 이름 |
| `WORKTREE_CONFLICT` | Worktree 충돌 |
| `AGENT_ERROR` | 에이전트 실행 실패 |
| `GIT_ERROR` | Git 명령 실패 |

```