Vibe Kanban — AI Agent Kanban Board

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

# 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

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

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

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

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

bash scripts/mcp-setup.sh --codex

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

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

Review the implementation plan for this feature with planno

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

vk/<4-char ID>-<task-slug>
e.g.: vk/3816-add-a-comment-to-readme

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

# 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

# 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

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

# 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

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

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

# Check API keys
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

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

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

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

"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

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

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

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

# 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

┌─────────────────────────────────────────────────────────┐
│                    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              # 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

# 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

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