플랫폼별 적용 상태 (현재 지원 기준)

플랫폼	현재 지원 방식	적용 조건
Claude	네이티브 MCP 연동	`mcpServers` 등록
Codex	MCP 스크립트 연동	`scripts/mcp-setup.sh --codex` 또는 동일 설정
Gemini	MCP 등록	`mcpServers` /브릿지 구성
OpenCode	MCP/브릿지 연동	`omx` / `ohmg` 류 또는 동등 구성

현재 스킬만

으로 가능한지:

Claude/Gemini: 가능
Codex: 가능(스크립트 기반 설정 필요)
OpenCode: 가능(오케스트레이션 경유)

Vibe Kanban — AI 에이전트 칸반 보드

여러 AI 에이전트(Claude/Codex/Gemini)를 하나의 Kanban 보드에서 통합 관리합니다. 카드(태스크)를 In Progress로 옮기면 git worktree 생성 + 에이전트 실행이 자동 시작됩니다.

When to use this skill

에픽을 여러 독립 태스크로 분해해 에이전트에게 병렬 할당할 때
진행 중인 AI 작업 상태를 시각적으로 추적하고 싶을 때
에이전트 결과를 UI에서 diff/로그로 리뷰하고 재시도하고 싶을 때
GitHub PR 기반 팀 협업과 AI 에이전트 작업을 결합할 때

전제 조건

bash

# Node.js 18+ 필요
node --version

# 에이전트 인증 미리 완료
claude --version    # ANTHROPIC_API_KEY 설정
codex --version     # OPENAI_API_KEY 설정 (선택)
gemini --version    # GOOGLE_API_KEY 설정 (선택)
opencode --version  # 별도 설정 없음 (GUI 기반)

검증된 버전 (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

설치 & 실행

npx (가장 빠름)

bash

# 즉시 실행 (설치 불필요)
npx vibe-kanban

# 포트 지정 (기본 포트 3000)
npx vibe-kanban --port 3001

# 포트와 환경 변수 동시 지정
PORT=3001 npx vibe-kanban --port 3001

# 래퍼 스크립트 사용
bash scripts/vibe-kanban-start.sh

브라우저에서

http://localhost:3000

자동 오픈.

⚠️ 포트 충돌 주의: Next.js 등 다른 개발 서버가 3000 포트를 사용 중이라면
PORT=3001 npx vibe-kanban --port 3001
로 실행하세요. 시작 로그에서
Main server on :3001
확인 후
http://localhost:3001
접속.

시작 시 정상 로그:

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

직접 클론 + 개발 모드

bash

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

환경 변수

변수	설명	기본값
`PORT`	서버 포트	`3000`
`HOST`	서버 호스트	`127.0.0.1`
`VIBE_KANBAN_REMOTE`	원격 연결 허용	`false`
`VK_ALLOWED_ORIGINS`	CORS 허용 출처	미설정
`DISABLE_WORKTREE_CLEANUP`	worktree 정리 비활성화	미설정
`ANTHROPIC_API_KEY`	Claude Code 에이전트용	—
`OPENAI_API_KEY`	Codex/GPT 에이전트용	—
`GOOGLE_API_KEY`	Gemini 에이전트용	—

.env

파일에 설정 후 서버 시작.

에이전트별 API 키 설정 위치 (Settings → Agents → Environment variables)
Claude Code:
ANTHROPIC_API_KEY
Codex:
OPENAI_API_KEY
Gemini:
GOOGLE_API_KEY
Opencode: 별도 설정 없음 (내장 인증)

MCP 설정

Vibe Kanban은 MCP(Model Context Protocol) 서버로 동작하여 에이전트가 직접 보드를 제어할 수 있습니다.

Claude Code MCP 설정

~/.claude/settings.json

또는 프로젝트의

.mcp.json

json

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

OpenCode MCP 설정

~/.config/opencode/opencode.json

에 추가:

json

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

재시작 후

vk_*

도구가 OpenCode 세션에서 바로 사용 가능합니다.

MCP 도구 목록

도구	설명
`vk_list_cards`	모든 카드(워크스페이스) 조회
`vk_create_card`	새 카드 생성
`vk_move_card`	카드 상태 변경
`vk_get_diff`	카드 diff 조회
`vk_retry_card`	카드 재실행

⚠️ 이전 버전 도구명과 변경:
vk_list_tasks
→
vk_list_cards
,
vk_create_task
→
vk_create_card
v0.1.17 기준 실제 MCP API에서 확인된 도구명입니다.

Codex MCP 적용

Codex에서 Vibe Kanban을 연동하려면 프로젝트 루트에서 다음을 실행합니다.

bash

bash scripts/mcp-setup.sh --codex

이 명령은

~/.codex/config.toml

에

vibe-kanban

MCP 서버 설정을 추가합니다.
훅 기반 자동 반복은 Codex 기본 동작이 아니므로, 재시도/반복 운영은 보드 카드 진행 상태 또는 상위 오케스트레이션으로 관리합니다.

워크스페이스 → 병렬 에이전트 → PR 워크플로우

v0.1.17 실제 UI 구조: Vibe Kanban은 Kanban 보드 형태이지만, 실제 작업 단위는 Workspace (워크스페이스)입니다. 각 워크스페이스가 하나의 태스크를 독립적으로 처리합니다.

1. 서버 시작

bash

# 기본 실행
npx vibe-kanban
# → http://localhost:3000

# 포트 충돌 시 (Next.js 등)
PORT=3001 npx vibe-kanban --port 3001
# → http://localhost:3001

2. (선택) planno로 에픽 계획 검토

text

planno로 이 기능의 구현 계획을 검토해줘

planno(plannotator)는 독립 스킬 — Vibe Kanban 없이도 사용 가능.

3. 워크스페이스 생성 (Create Workspace)

UI 접속 → "+ Create Workspace" 또는 왼쪽 사이드바
```
+
```
버튼 클릭
Which repositories? 화면:
- Browse → 파일 시스템에서 git 레포 선택 (경로 수동 입력 가능)
- Recent → 이전에 사용한 레포
- 레포 선택 후 브랜치 선택 (기본:
```
main
```
  )
- Continue 클릭
What would you like to work on? 화면:
- 에이전트 선택 (Opencode, Claude Code, Codex, Gemini, Amp, Qwen Code, Copilot, Droid, Cursor Agent)
- 태스크 설명 입력 (Markdown 지원)
- 모드 선택 (Default, Build 등)
- Create 클릭

4. 에이전트 자동 실행

워크스페이스 생성 시:

vk/<hash>-<slug>

브랜치 자동 생성 (예:

vk/3816-add-a-comment-to

)

git worktree 자동 생성 (에이전트별 완전 격리)
선택한 에이전트 CLI 실행 + 로그 스트리밍

워크스페이스 상태:

Running: 에이전트 실행 중 (왼쪽 사이드바)
Idle: 대기 중
Needs Attention: 에이전트 완료 또는 입력 필요

5. 결과 확인

Changes 패널: 파일 diff 확인
Logs 패널: 에이전트 실행 로그
Preview 패널: 웹앱 미리보기
Terminal: 직접 명령 실행
Notes: 메모 작성

6. PR 생성 & 완료

워크스페이스 상세 → "Open pull request" 버튼
PR merge → 워크스페이스 Archive로 이동
worktree 자동 정리

Git Worktree 격리 구조

워크스페이스 디렉토리 (Settings → General → Workspace Directory에서 변경 가능):

~/.vibe-kanban-workspaces/          ← 기본 위치 (홈 디렉토리 하위)
├── <workspace-uuid-1>/             ← 워크스페이스1 격리 환경
├── <workspace-uuid-2>/             ← 워크스페이스2 격리 환경
└── <workspace-uuid-3>/             ← 워크스페이스3 격리 환경

브랜치 네이밍 (Settings → General → Git → Branch Prefix에서 변경):

vk/<4자 ID>-<task-slug>
예: vk/3816-add-a-comment-to-readme

내부 동작:

bash

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

.gitignore 권장 항목 추가:
.vibe-kanban-workspaces/
.vibe-kanban/

원격 배포

Docker

bash

# 공식 이미지
docker run -p 3000:3000 vibekanban/vibe-kanban

# 환경 변수 전달
docker run -p 3000:3000 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e VK_ALLOWED_ORIGINS=https://vk.example.com \
  vibekanban/vibe-kanban

리버스 프록시 (Nginx/Caddy)

bash

# CORS 허용 필수
VK_ALLOWED_ORIGINS=https://vk.example.com

# 또는 다중 출처
VK_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com

SSH 원격 열기

VSCode Remote-SSH와 통합:

vscode://vscode-remote/ssh-remote+user@host/path/to/.vk/trees/<task-slug>

트러블슈팅

Worktree 충돌 / 고아 worktree

bash

# 고아 worktree 정리
git worktree prune

# 현재 worktree 목록 확인
git worktree list

# 특정 worktree 강제 삭제
git worktree remove .vk/trees/<slug> --force

403 Forbidden (CORS 오류)

bash

# 원격 접속 시 CORS 설정 필요
VK_ALLOWED_ORIGINS=https://your-domain.com npx vibe-kanban

에이전트가 시작되지 않음

bash

# CLI 직접 테스트
claude --version
codex --version

# API 키 확인
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

포트 충돌

bash

# 다른 포트 사용
npx vibe-kanban --port 3001

# 또는 환경 변수
PORT=3001 npx vibe-kanban

SQLite 락 오류

bash

# worktree 정리 비활성화 후 재시작
DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban

UI vs CLI 선택 기준

상황	모드
팀 공유 보드, 시각적 진행 추적	UI ( `npx vibe-kanban` )
CI/CD 파이프라인, 스크립트 자동화	CLI ( `scripts/pipeline.sh` )
빠른 로컬 실험	CLI ( `scripts/conductor.sh` )
브라우저 diff/로그 리뷰	UI

지원 에이전트 목록 (v0.1.17 검증)

Settings → Agents에서 각 에이전트별 상세 설정 가능:

에이전트	명령	API 키
Opencode	`opencode`	내장 (기본값)
Claude Code	`claude`	`ANTHROPIC_API_KEY`
Codex	`codex`	`OPENAI_API_KEY`
Gemini	`gemini`	`GOOGLE_API_KEY`
Amp	`amp`	별도
Qwen Code	`qwen-coder`	별도
Copilot	`copilot`	GitHub 계정
Droid	`droid`	별도
Cursor Agent	`cursor`	Cursor 구독

에이전트별 설정 가능 항목:

Append prompt: 에이전트 실행 시 추가 지시문
Model: 사용할 모델명 (예:
```
claude-opus-4-6
```
)
Variant: 모델 변형
Auto Approve: 에이전트 액션 자동 승인 (기본: ON)
Auto Compact: 컨텍스트 자동 압축 (기본: ON)
Environment variables: API 키 등 환경변수

대표 사용 케이스

1. 에픽 병렬 분해 처리

"결제 플로우 v2" 에픽
  ├── 워크스페이스1: 프론트엔드 UI  → Claude Code
  ├── 워크스페이스2: 백엔드 API     → Codex
  └── 워크스페이스3: 통합 테스트    → Opencode
→ 3개 워크스페이스 동시 Running → 병렬 구현

2. 역할별 전문 에이전트 배치

Claude Code  → 설계/도메인 heavy 기능
Codex        → 타입/테스트/리팩터링
Gemini       → 문서/스토리북 작성
Opencode     → 범용 작업 (기본값)

3. GitHub PR 기반 팀 협업

VIBE_KANBAN_REMOTE=true 설정
→ 팀원이 보드에서 상태 확인
→ GitHub PR에서만 리뷰/승인
→ 에이전트 병렬 + 전통 PR 프로세스 결합

4. 구현 비교

동일 태스크, 두 개 워크스페이스:
  워크스페이스A → Claude Code (UI 구조 중심)
  워크스페이스B → Codex (성능 최적화 중심)
→ PR 비교 후 best-of-both 선택

5. OpenCode + ulw 병렬 위임

OpenCode의 ulw(ultrawork) 모드와 결합해 에이전트를 에픽 단위로 병렬 실행:

python

# ulw 키워드 → ultrawork 병렬 실행 레이어 활성화
# Vibe Kanban 보드: npx vibe-kanban (별도 터미널에서 실행)

task(category="visual-engineering", run_in_background=True,
     load_skills=["frontend-ui-ux", "vibe-kanban"],
     description="[Kanban WS1] 프론트엔드 UI",
     prompt="결제 플로우 UI 구현 — src/components/payment/ 내 카드 입력, 주문 확인, 완료 화면")

task(category="unspecified-high", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[Kanban WS2] 백엔드 API",
     prompt="결제 플로우 API 구현 — POST /charge, POST /refund, GET /status/:id")

task(category="unspecified-low", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[Kanban WS3] 통합 테스트",
     prompt="결제 E2E 테스트 작성 — 성공/실패/환불 시나리오")

# → 3개 워크스페이스가 Running 상태로 Kanban 보드에 동시 표시
# → 각 완료 시: Needs Attention → PR 생성 → Archive

팁

카드 범위를 좁게 유지 (1카드 = 1커밋 단위)
2개 파일 이상 변경 시 planno로 먼저 계획 검토
```
VIBE_KANBAN_REMOTE=true
```
는 신뢰 네트워크에서만 사용
에이전트 스탈 시 → 재할당 또는 카드 분할

아키텍처 개요

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

참고 레퍼런스

스킬 파일 구조

.agent-skills/vibe-kanban/
├── SKILL.md              # 메인 스킬 문서
├── SKILL.toon            # TOON 형식 (압축)
├── scripts/
│   ├── start.sh          # 서버 시작 래퍼
│   ├── cleanup.sh        # Worktree 정리
│   ├── mcp-setup.sh      # MCP 설정 자동화
│   └── health-check.sh   # 서버 상태 확인
├── references/
│   ├── environment-variables.md  # 환경 변수 레퍼런스
│   └── mcp-api.md                # MCP API 레퍼런스
└── templates/
    ├── claude-mcp-config.json    # Claude Code MCP 설정
    ├── docker-compose.yml        # Docker 배포 템플릿
    └── .env.example              # 환경 변수 예시

스크립트 사용법

bash

# 서버 시작
bash scripts/start.sh --port 3001

# Worktree 정리
bash scripts/cleanup.sh --dry-run  # 미리보기
bash scripts/cleanup.sh --all       # 모든 VK worktree 삭제

# MCP 설정
bash scripts/mcp-setup.sh --claude  # Claude Code 설정
bash scripts/mcp-setup.sh --all     # 모든 에이전트 설정

# 상태 확인
bash scripts/health-check.sh
bash scripts/health-check.sh --json  # JSON 출력

Quick Reference

=== 서버 실행 ===
npx vibe-kanban                       즉시 실행 (포트 3000)
PORT=3001 npx vibe-kanban --port 3001 포트 충돌 시 (Next.js 등)
http://localhost:3000                  보드 UI

=== 환경 변수 ===
PORT=3001                        포트 변경
VK_ALLOWED_ORIGINS=https://...   CORS 허용
ANTHROPIC_API_KEY=...            Claude Code 인증
OPENAI_API_KEY=...               Codex 인증
GOOGLE_API_KEY=...               Gemini 인증

=== MCP 연동 ===
npx vibe-kanban --mcp            MCP 모드
vk_list_cards                    카드(워크스페이스) 조회
vk_create_card                   카드 생성
vk_move_card                     상태 변경

=== 워크스페이스 흐름 ===
Create → Running → Needs Attention → Archive
Running: worktree 생성 + 에이전트 시작
Needs Attention: 완료 또는 입력 필요
Archive: PR merge 완료

=== MCP 설정 파일 위치 ===
Opencode: ~/.config/opencode/opencode.json
Claude Code: ~/.claude/settings.json 또는 .mcp.json

=== worktree 정리 ===
git worktree prune               고아 정리
git worktree list                목록 확인
git worktree remove <path>       강제 삭제

vibe-kanban

NPX Install

Tags

SKILL.md Content

플랫폼별 적용 상태 (현재 지원 기준)

Vibe Kanban — AI 에이전트 칸반 보드

When to use this skill

전제 조건

설치 & 실행

npx (가장 빠름)

직접 클론 + 개발 모드

환경 변수

MCP 설정

Claude Code MCP 설정

OpenCode MCP 설정

MCP 도구 목록

Codex MCP 적용

워크스페이스 → 병렬 에이전트 → PR 워크플로우

1. 서버 시작

2. (선택) planno로 에픽 계획 검토

3. 워크스페이스 생성 (Create Workspace)

4. 에이전트 자동 실행

5. 결과 확인

6. PR 생성 & 완료

Git Worktree 격리 구조

원격 배포

Docker

리버스 프록시 (Nginx/Caddy)

SSH 원격 열기

트러블슈팅

Worktree 충돌 / 고아 worktree

403 Forbidden (CORS 오류)

에이전트가 시작되지 않음

포트 충돌

SQLite 락 오류

UI vs CLI 선택 기준

지원 에이전트 목록 (v0.1.17 검증)

대표 사용 케이스

1. 에픽 병렬 분해 처리

2. 역할별 전문 에이전트 배치

3. GitHub PR 기반 팀 협업

4. 구현 비교

5. OpenCode + ulw 병렬 위임

팁

아키텍처 개요

참고 레퍼런스

스킬 파일 구조

스크립트 사용법

Quick Reference