vibe-kanban

Original：🇺🇸 English

Translated

4 scripts

Manage AI coding agents on a visual Kanban board. Run parallel agents through a To Do→In Progress→Review→Done flow with automatic git worktree isolation and GitHub PR creation.

4installs

Sourceakillness/oh-my-skills

Added on2026-04-03

NPX Install

npx skill4agent add akillness/oh-my-skills vibe-kanban

SKILL.md Content

View Translation Comparison →

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

bash

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

bash

# 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

bash

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

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

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

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

bash

# 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

text

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:

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:

bash

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

bash

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

bash

# 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

bash

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

bash

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

Agent won't start

bash

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

# Check API keys
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

Port conflict

bash

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

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

SQLite lock error

bash

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

python

# 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

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

bash

# 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

vibe-kanban

NPX Install

Tags

SKILL.md Content

Platform Support Status (Current)

Vibe Kanban — AI Agent Kanban Board

When to use this skill

Prerequisites

Installation & Running

npx (fastest)

Clone + dev mode

Environment Variables

MCP Configuration

Claude Code MCP Setup

OpenCode MCP Setup

MCP Tool List

Codex MCP Integration

Workspace → Parallel Agents → PR Workflow

1. Start the server

2. (Optional) Review epic plan with planno

3. Create a Workspace

4. Automatic agent execution

5. Review results

6. Create PR & finish

Git Worktree Isolation Structure

Remote Deployment

Docker

Reverse Proxy (Nginx/Caddy)

SSH Remote Access

Troubleshooting

Worktree conflicts / orphaned worktrees

403 Forbidden (CORS error)

Agent won't start

Port conflict

SQLite lock error

UI vs CLI Decision Guide

Supported Agents (verified v0.1.17)

Representative Use Cases

1. Parallel epic decomposition

2. Role-based specialist agent assignment

3. GitHub PR-based team collaboration

4. Implementation comparison

5. OpenCode + ulw parallel delegation

Tips

Architecture Overview

References

Skill File Structure

Script Usage

Quick Reference