
Vibe Kanban
- 235 installs
- 40 repo stars
- Updated August 4, 2026
- akillness/oh-my-skills
Run a lightweight kanban board tailored to vibe-coding sessions so agents and humans track tasks, WIP limits, and delivery rhythm without heavy PM tooling overhead.
About
Provides kanban-style project management for vibe-coding workflows: define columns and WIP limits, slice backlog into agent-friendly tasks, track status across sessions, and keep build momentum visible without enterprise PM overhead.
- Kanban columns tuned for agent-assisted coding
- WIP limits and session-based task slicing
- Backlog intake from prompts and discoveries
- Status tracking across human and agent owners
- Lightweight ceremony for fast iteration cycles
Vibe Kanban by the numbers
- 235 all-time installs (skills.sh)
- Ranked #980 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/akillness/oh-my-skills --skill vibe-kanbanAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 235 |
|---|---|
| repo stars | ★ 40 |
| Last updated | August 4, 2026 |
| Repository | akillness/oh-my-skills ↗ |
What it does
Run a lightweight kanban board tailored to vibe-coding sessions so agents and humans track tasks, WIP limits, and delivery rhythm without heavy PM tooling overhead.
Files
Vibe Kanban
vibe-kanban is the coding-board / workspace / review control-plane skill.
Use it when the hard part is coordinating bounded coding tasks through a visible board, isolated workspaces, human review, retries, and PR handoff.
Read these support docs before you pick the workflow shape:
- references/modes-and-routing.md
- references/board-packets-and-surface-selection.md
- references/review-and-cleanup.md
- references/tracker-and-non-code-boundaries.md
- references/environment-variables.md
- references/mcp-api.md
When to use this skill
Use vibe-kanban when one or more of these are true:
- The user needs a visual board or workspace queue for coding tasks.
- The workflow requires parallel workspaces/worktrees instead of one long agent session.
- A human must review diffs, retries, or PR handoff across several coding cards.
- The operator wants one control plane for branch isolation, agent assignment, review, and cleanup.
- The board should stay linked to an existing tracker without replacing it as the PM source of truth.
- The request mentions kanban board, review queue, worktree board, coding tracker sync, parallel coding agents, or
vibe-kanban.
When not to use this skill
- Planning, decomposition, or sign-off comes before any coding board → use
task-planning,survey,jeo, orplannotator - The task is a single-agent coding run with no board/review/workspace need → use the relevant coding/orchestration skill directly
- The real requirement is browser review or authenticated browser reuse → use
agentation,browser-harness, orplaywriter - The work is mostly PM / ops coordination without coding workspaces, diffs, or PRs → use PM workflow skills such as
task-planning,standup-meeting, orsprint-retrospective - The work is mainly marketing/content operations → use
marketing-automationor adjacent GTM/content skills - The work is game-production planning without coding-board execution → use
bmad-gdsor other game-production skills
Quick routing rule
| If the job needs... | Use |
|---|---|
| A board for bounded coding tasks with worktrees, review, retries, and PR handoff | vibe-kanban |
| Plan review or artifact approval before coding begins | plannotator |
| One agent task with no board/workspace control plane | direct coding/orchestration skill |
| Exact rendered-UI review or browser-state reuse | agentation / playwriter / browser-harness |
| Non-code work coordination (PM, marketing, game ops) | the matching domain workflow skill |
Instructions
Step 1: Confirm that the board is the real need
Normalize the request before opening a board or configuring MCP.
vibe_kanban_mode:
board_need: coding-board | tracker-sync | review-queue | compare-agents | unknown
task_shape: single-bounded-task | several-independent-tasks | epic-needs-splitting | unknown
review_surface: board-review | PR-review | board-then-PR | unknown
repo_scope: one-repo | several-repos | no-repo | unknown
agent_mix: claude | codex | gemini | opencode | mixed | unknown
cleanup_need: low | medium | high | unknownChoose vibe-kanban only if the workflow truly needs a coding board. If the task is still a vague epic, split it before the board becomes noise.
Step 2: Keep one bounded coding task per card
Good cards have one reviewable outcome:
- one API endpoint
- one failing test cluster
- one isolated UI component
- one comparison between two agents on one task
Bad cards are giant epics such as “finish the migration” or mixed non-code/coding workflows.
Step 3: Pick the board packet and review surface
Use references/board-packets-and-surface-selection.md to choose among:
- parallel coding cards
- agent comparison
- review queue
- tracker sync
Default to board-then-PR when quick local iteration matters but the final review still belongs in GitHub.
Step 4: Treat each card as a workspace contract
Every card should capture:
- exact goal and acceptance checks
- repo + base branch
- chosen agent
- review surface
- cleanup owner
- tracker link if an external board remains canonical
Minimal card example:
Title: Fix signup validation regression
Goal: Restore server-side validation for missing email/phone on /signup
Acceptance: failing tests pass, new regression test added, PR ready for review
Agent: Claude Code
Review: board-then-PRStep 5: Run the board loop
1. Create or refine a bounded card 2. Start one isolated workspace for that card 3. Observe logs and diffs 4. Review against the card contract 5. Retry, split, approve, or hand off to PR review 6. Clean up branches/worktrees/servers explicitly
Step 6: Keep review and cleanup honest
Use references/review-and-cleanup.md for the acceptance loop. The short rule:
- compare output to the card contract, not just whether files changed
- prefer retry or split over letting one workspace drift forever
- do not treat board status as proof that the work is done
- close stale cards and prune stale worktrees on purpose
Step 7: Use MCP only when shared board control helps
Start with the UI or local workflow first. Bring in MCP when another orchestrator needs to create cards, inspect state, or move work programmatically.
Step 8: Route out honestly
Keep vibe-kanban narrow enough to stay useful.
- plan creation or approval →
task-planning,survey,plannotator,jeo - code review without a board/workspace loop →
code-review - browser review or QA evidence →
agentation,browser-harness,playwriter - PM-only rituals or roadmap coordination → PM skills
- marketing/content pipeline coordination without coding workspaces →
marketing-automation - game-production planning without coding-board control →
bmad-gds
High-value command patterns
# start local board on a safe port
PORT=3001 npx vibe-kanban --port 3001
# run MCP server for orchestrators
npx vibe-kanban --mcp
# inspect worktree cleanup state
git worktree list
git worktree pruneExamples
Example 1: Parallel coding board
- Prompt: “Set up a board so Claude and Codex can each take one of these three independent bug fixes, and I can review diffs before opening PRs.”
- Expected behavior: use
vibe-kanban, create bounded cards, keep workspaces isolated, and choose a board-review → PR handoff loop.
Example 2: Agent comparison
- Prompt: “Run two agents against the same API bug so I can compare their diffs and decide which PR to keep.”
- Expected behavior: use
vibe-kanban, preserve isolated attempts, and make the review decision explicit.
Example 3: Planning only
- Prompt: “Help me break this migration into phases and get sign-off before any code is written.”
- Expected behavior: route to
task-planningorplannotator, because the board is premature.
Example 4: Marketing board
- Prompt: “I need a board for content calendar approvals and launch copy revisions.”
- Expected behavior: route to
marketing-automationor PM/content workflow skills, becausevibe-kanbanis for coding workspaces, diffs, and PR handoff.
Example 5: Tracker-linked coding board
- Prompt: “Keep GitHub Projects as the source of truth, but open a coding board for three worktree-isolated feature cards and hand each finished card to PR review.”
- Expected behavior: keep the tracker canonical, use
vibe-kanbanfor coding execution state, and preserve explicit cleanup/PR handoff.
Best practices
1. Keep one bounded coding outcome per card. 2. Treat GitHub Projects / Linear / Jira as external trackers, not proof that a coding board is unnecessary. 3. Limit active cards to what one reviewer can realistically absorb. 4. Preserve retry decisions and comments somewhere durable. 5. Prefer board-then-PR for fast iteration on shared repos. 6. Clean up worktrees, branches, and preview servers as part of the workflow. 7. Route PM, marketing, and non-code game-production boards away early.
References
{
"skill_name": "vibe-kanban",
"evals": [
{
"id": 1,
"prompt": "Set up a kanban board so Claude and Codex can each take one of these three independent bug fixes, and I can review diffs before opening PRs.",
"expected_output": "The skill chooses vibe-kanban, treats the work as bounded coding cards, emphasizes isolated workspaces/worktrees, and frames review before PR handoff.",
"assertions": [
"Mentions board or workspace control plane for coding tasks",
"Keeps one bounded task per card or workspace",
"Includes review before PR handoff",
"Mentions isolated workspaces, worktrees, or parallel coding agents"
]
},
{
"id": 2,
"prompt": "Run two agents against the same API bug so I can compare their diffs and decide which PR to keep.",
"expected_output": "The skill uses vibe-kanban in comparison mode and explains review criteria, isolated attempts, and explicit retry/approval choices.",
"assertions": [
"Mentions comparison between agent attempts",
"Preserves isolated workspaces or branches for each attempt",
"Explains that human review decides which result to keep"
]
},
{
"id": 3,
"prompt": "Help me break this migration into phases and get sign-off before any code is written.",
"expected_output": "The skill routes away from vibe-kanban because the request is planning-first and a board/workspace loop is premature.",
"assertions": [
"Routes to planning or review skills such as task-planning or plannotator",
"Explains that vibe-kanban is for running coding-task boards rather than pre-coding planning"
]
},
{
"id": 4,
"prompt": "I need a board for launch-copy approvals and content calendar changes across marketing and design.",
"expected_output": "The skill routes away from vibe-kanban and explains that the request is marketing/content coordination without coding workspaces, diffs, or PR review.",
"assertions": [
"Routes to marketing-automation or a PM/content workflow skill",
"Explains that vibe-kanban is for coding boards with workspaces/review/PR handoff"
]
},
{
"id": 5,
"prompt": "Keep GitHub Projects as the source of truth, but open a coding board for three worktree-isolated feature cards and hand each finished card to PR review.",
"expected_output": "The skill keeps the external tracker canonical while using vibe-kanban for coding execution state, isolated workspaces, and explicit review/cleanup handoff.",
"assertions": [
"Mentions tracker-linked coding board or tracker sync",
"Keeps GitHub Projects or the external tracker as the source of truth",
"Includes isolated workspaces or worktrees plus PR handoff",
"Mentions cleanup ownership or explicit cleanup"
]
}
]
}
Board Packets and Surface Selection
Use this packet when the operator is not deciding whether to use vibe-kanban, but how to shape the board once a coding-board workflow is justified.
Choose the board packet
| Packet | Use when | Required fields | Route out when |
|---|---|---|---|
| Parallel coding cards | Several independent coding tasks can run without stepping on each other | repo, base branch, one bounded outcome per card, assigned agent, review surface | the tasks are still one giant epic |
| Agent comparison | Two agents should attack the same bounded task independently | comparison question, identical task contract, separate branches/workspaces, explicit decision rule | the operator only wants plan review |
| Review queue | The hard part is no longer execution, but judging retries vs approval across active cards | review owner, evidence source, retry policy, PR handoff rule | there is no real board lifecycle |
| Tracker sync | GitHub Projects / Linear / Jira remains the source of truth, but coding workspaces still need a control plane | tracker item link, coding task scope, workspace owner, cleanup owner | the external tracker alone is enough |
Recommended surface choices
| Decision | Good default | Why |
|---|---|---|
| Card scope | one bounded coding task | keeps retries, review, and cleanup cheap |
| Review surface | board-then-PR | fast local iteration without losing durable review history |
| Workspace isolation | one branch/worktree per active card | reduces collisions and blame confusion |
| Active parallelism | only as many cards as one reviewer can realistically absorb | review is usually the real bottleneck |
| Tracker relationship | keep the tracker canonical, let vibe-kanban own coding execution state | prevents a second PM system from taking over |
Practical intake fields
Before opening or syncing a card, capture:
- exact goal and acceptance checks
- repo and base branch
- agent selection
- review surface (
board-first,PR-first, orboard-then-PR) - cleanup owner
- tracker link if an external board remains canonical
Common failure modes
- Board opened too early: the work was still an epic or planning discussion.
- Parallelism outran review: several cards were active, but nobody could compare diffs fast enough.
- Tracker confusion: status drifted between GitHub/Linear/Jira and the board.
- Cleanup skipped: stale
vk/*branches, worktrees, or preview servers accumulated.
Route-outs to keep honest
- planning and approval before coding →
task-planning,survey,plannotator,jeo - code review without a real board lifecycle →
code-review - exact rendered-UI/browser work →
agentation,browser-harness,playwriter - PM rituals or roadmap coordination → PM skills
- marketing/content approvals →
marketing-automation - non-code milestone / launch planning in games →
bmad-gds
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 파일
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 환경
docker run -p 3000:3000 \
-e VIBE_KANBAN_REMOTE=true \
-e VK_ALLOWED_ORIGINS=https://vk.example.com \
vibekanban/vibe-kanbanVibe 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) |
응답:
[
{
"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) |
응답:
{
"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) |
응답:
{
"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) |
응답:
{
"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) |
응답:
{
"id": "card_abc123",
"column": "in_progress",
"retry_count": 2
}에러 코드
| 코드 | 설명 |
|---|---|
CARD_NOT_FOUND | 카드를 찾을 수 없음 |
INVALID_COLUMN | 잘못된 칼럼 이름 |
WORKTREE_CONFLICT | Worktree 충돌 |
AGENT_ERROR | 에이전트 실행 실패 |
GIT_ERROR | Git 명령 실패 |
Vibe Kanban Modes and Routing
Use this note when deciding whether vibe-kanban is the right surface.
Core rule
vibe-kanban is for coding-task orchestration with a visible board, isolated workspaces, human review, retries, and PR handoff.
If the real need is missing one of those pieces, another skill is usually a better fit.
Modes
| Mode | Use when | Primary value | Common route-outs |
|---|---|---|---|
| Coding board | Several bounded coding tasks need card/workspace control | Board + worktree isolation + review queue | direct coding skill if only one task exists |
| Review queue | Work is already running but human review/retry choice is the bottleneck | Visible review state and evidence-based retries | code-review if there is no board lifecycle |
| Agent comparison | Two agents should attack one bounded task independently | Side-by-side diff comparison before choosing a PR | plannotator if the work is still plan review only |
| Tracker sync | Board status should mirror a repo/task system | Shared control plane plus external tracking | Existing tracker-only workflow if board adds no value |
Route-outs
- Planning before coding →
task-planning,survey,plannotator - Single-agent coding run → direct coding/orchestration skill
- Browser review / exact UI feedback →
agentation,browser-harness,playwriter - PM-only rituals →
task-planning,standup-meeting,sprint-retrospective - Marketing/content coordination →
marketing-automation - Game-production planning without coding workspaces →
bmad-gds
Smell tests
If any of these are true, the board is probably premature:
- the task is one giant epic with no real card boundaries
- the operator cannot review the resulting diffs
- there is no repo or branch context yet
- the request is mostly about docs, campaigns, or status meetings
- the operator only wants a checklist, not a workspace control plane
Review and Cleanup Checklist
Review loop
Before approving a workspace/card outcome, check: 1. Does the diff match the card contract? 2. Are acceptance checks or tests mentioned and believable? 3. Should this be retried, split, or escalated to PR review? 4. Are comments or reviewer notes preserved somewhere durable? 5. Does the card status reflect reality, not wishful thinking?
Retry guidance
Retry when:
- the task is still bounded and the current attempt mostly failed on execution
- the operator has clear feedback to send back
- the workspace context is still trustworthy
Split or recreate instead when:
- the card scope was wrong from the start
- the workspace accumulated too much junk or drift
- several unrelated changes are bundled together
- preview/runtime conflicts are making evidence unreliable
Cleanup pass
After merge / close / abandon:
- close stale cards explicitly
- remove or prune stale worktrees
- delete stale
vk/*branches when safe - stop leftover preview/dev servers
- capture any durable decision that would otherwise vanish with the card
Why this matters
Board tools create invisible debt when cleanup is skipped. The workflow is only better than plain PR review if it reduces chaos instead of creating a bigger pile of stale branches, logs, and half-reviewed workspaces.
Tracker and Non-Code Boundaries
vibe-kanban overlaps with several adjacent workflows. This note keeps the boundary clear.
Existing trackers vs vibe-kanban
Use an existing tracker alone when the team only needs:
- issue assignment
- status visibility
- comments/audit trail
- sprint or roadmap management
Add vibe-kanban when the team also needs:
- isolated coding workspaces/worktrees per task
- explicit agent selection and retries
- fast board-first review before PR handoff
- comparison between multiple agent attempts on bounded code work
PM / ops
If the request is really about standups, retros, prioritization, or status reporting, route to PM skills.
Marketing / content
If the workflow is mostly briefs, calendars, approvals, launch messaging, or content operations, route to marketing-automation or related GTM/content skills. Many teams use boards or spreadsheets there, but they do not need coding workspaces, diffs, or PR cleanup.
Game development
If the request is about production planning, pitch decks, milestone reviews, or feature prioritization without a coding-board control plane, route to bmad-gds or the relevant game workflow skill. Use vibe-kanban only when game work is actually being executed as bounded coding tasks on a board.
Practical operator question
Ask: Will success be judged mainly through diffs, workspaces, retries, and PR handoff?
- If yes,
vibe-kanbanmay fit. - If no, use the domain workflow skill and keep the board out of the way.
#!/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
#!/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 "상태 확인 완료"
#!/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: 에이전트 로그 조회"
#!/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
N:vibe-kanban
V:2.1.0
D:Coding-board control plane for bounded coding cards, isolated workspaces/worktrees, review queues, retries, and PR handoff. Use when the user needs a visual board or tracker-linked workspace loop for parallel coding tasks, agent comparison, or review-heavy handoff.
G:vibe-kanban kanban kanbanview coding-board workspace-board review-queue tracker-sync worktree github-pr claude-code codex gemini opencode
U[6]:
Run a visible coding board for bounded tasks with isolated workspaces
Keep tracker-linked coding execution separate from PM source-of-truth boards
Compare agent attempts and preserve explicit review criteria
Move work through review then PR handoff instead of relying on chat memory
Treat cleanup of worktrees branches and servers as part of the board loop
Route planning browser-review and non-code board requests away early
S[5]{n,action,details}:
1,Classify,Decide whether the request truly needs a coding board or only planning/tracker/browser help
2,Scope,Keep one bounded coding task per card and choose the board packet
3,Run,Launch isolated workspaces and set the review surface for each card
4,Review,Compare output against the card contract and choose retry split approve or PR handoff
5,Cleanup,Close stale cards prune worktrees and remove leftover branches or servers
R[5]:
Use vibe-kanban only when board control review and workspace isolation materially matter
Keep GitHub Projects Linear or Jira canonical when they remain the PM tracker
Limit active cards to what a human reviewer can really evaluate
Prefer board-then-PR when shared repos need both fast iteration and durable review
Route PM marketing and non-code game-production coordination to other skills
E[5]{desc,in,out}:
"Parallel bugfix board","Set up a board so Claude and Codex each handle one frontend bug and I can review diffs before PRs","Create bounded cards and isolated workspaces with review then PR flow"
"Agent comparison","Run two agents on the same API bug so I can compare diffs and decide which PR to keep","Preserve isolated attempts and explicit review criteria"
"Planning only","Help me break this migration into phases before coding starts","Route to task-planning or plannotator instead of opening a board"
"Marketing board","I need a board for launch-copy approvals and content calendar changes","Route to marketing-automation or PM/content workflow skills"
"Tracker-linked coding board","Keep GitHub Projects canonical but run three coding cards in worktrees and hand each to PR review","Use vibe-kanban for coding execution state without replacing the tracker"
T[3]{problem,solution}:
"Cards keep stalling","Split them smaller and reduce active parallel work"
"Review backlog grows","Lower active card count or switch to board-then-PR / PR-first review"
"Worktree mess","Run cleanup steps and close stale cards explicitly"
PORT=3000
VIBE_KANBAN_REMOTE=false
VIBE_KANBAN_DATA_DIR=.vibe-kanban
MCP_HOST=127.0.0.1
MCP_PORT=3001
VK_ALLOWED_ORIGINS=http://localhost:3000
ANTHROPIC_API_KEY=sk-ant-api...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AI...
GITHUB_TOKEN=ghp_...
{
"mcpServers": {
"vibe-kanban": {
"command": "npx",
"args": ["vibe-kanban", "--mcp"],
"env": {
"MCP_HOST": "127.0.0.1",
"MCP_PORT": "3001"
}
}
}
}
version: '3.8'
services:
vibe-kanban:
image: vibekanban/vibe-kanban:latest
container_name: vibe-kanban
ports:
- "3000:3000"
- "3001:3001"
environment:
- PORT=3000
- MCP_PORT=3001
- VIBE_KANBAN_REMOTE=true
- VK_ALLOWED_ORIGINS=${VK_ALLOWED_ORIGINS:-http://localhost:3000}
volumes:
- ./data:/app/.vibe-kanban
- /var/run/docker.sock:/var/run/docker.sock
restart: unless-stopped
nginx:
image: nginx:alpine
container_name: vibe-kanban-proxy
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./certs:/etc/nginx/certs:ro
depends_on:
- vibe-kanban
restart: unless-stopped