vibe-kanban

$2a

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

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

# 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

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:

{

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

{

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

# 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

Review the implementation plan for this feature with planno

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

3. Create a Workspace

• Open the UI → click "+ Create Workspace" or the + button in the left sidebar

• 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

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

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

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

# 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

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

# CORS config required for remote access

VK_ALLOWED_ORIGINS=https://your-domain.com npx vibe-kanban

Agent won't start

# Test CLI directly

claude --version

codex --version

# Check API keys

echo $ANTHROPIC_API_KEY

echo $OPENAI_API_KEY

Port conflict

# Use a different port

npx vibe-kanban --port 3001

# Or use environment variable

PORT=3001 npx vibe-kanban

SQLite lock error

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

# 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

• Official landing page: vibekanban.com

• Architecture analysis: vibe-kanban – a Kanban board for AI agents

• Adoption story

• Demo: Run Multiple Claude Code Agents Without Git Conflicts

• Demo: Claude Code Just Got Way Better | Auto Claude Kanban Boards

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

# 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