vibe-kanban▌
supercent-io/skills-template · updated Apr 8, 2026
MDX-style export adds YAML metadata + attribution linking explainx.ai and this canonical listing URL.
Manage multiple AI agents on a visual Kanban board with automatic git worktree isolation and GitHub PR creation.
- ›Supports parallel agent execution (Claude, Codex, Gemini, Opencode, and 4+ others) across isolated git worktrees, each with its own branch and workspace directory
- ›Provides a four-column board (To Do, In Progress, Review, Done) where moving a card automatically creates a worktree, starts the agent, and streams logs in real time
- ›Integrates as an MCP server with tools for lis
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. ConfirmMain server on :3001in the startup log, then visithttp://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_cardThese 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) |