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

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

(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.
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
Automatic agent execution

When a workspace is created:

A

vk/-

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
Review results

Changes panel

View file diffs

Logs panel

Agent execution logs

Preview panel

Web app preview

Terminal

Run commands directly

Notes

Write notes
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 1 isolated environment ├── / ← workspace 2 isolated environment └── / ← workspace 3 isolated environment Branch naming (configurable in Settings → General → Git → Branch Prefix): vk/<4-char ID>- 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 "" --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/ 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 Force remove

安装

Node.js 18+ required

Complete agent authentication beforehand

Set ANTHROPIC_API_KEY

Set OPENAI_API_KEY (optional)

Set GOOGLE_API_KEY (optional)

No separate setup needed (GUI-based)

Run immediately (no installation needed)

Specify port (default port 3000)

Specify port and environment variable together

PORT

Use wrapper script

Default run

→ http://localhost:3000

Port conflict (e.g., Next.js)

PORT

→ http://localhost:3001

Official image

Pass environment variables

CORS must be allowed

VK_ALLOWED_ORIGINS

Or multiple origins

VK_ALLOWED_ORIGINS

Clean up orphaned worktrees

List current worktrees

Force remove a specific worktree

CORS config required for remote access

VK_ALLOWED_ORIGINS

Test CLI directly

Check API keys

Use a different port

Or use environment variable

PORT

Disable worktree cleanup and restart

DISABLE_WORKTREE_CLEANUP

ulw keyword → activates ultrawork parallel execution layer

Vibe Kanban board: npx vibe-kanban (run in a separate terminal)

→ 3 workspaces appear simultaneously in Running state on the Kanban board

→ On each completion: Needs Attention → PR created → Archive

Start server

Worktree cleanup

Preview

Remove all VK worktrees

MCP setup

Claude Code setup

Setup for all agents

Health check

JSON output