vibe-kanban

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

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

1. Open the UI → click "+ Create Workspace" or the + button in the left sidebar
2. Which repositories? screen:
3. Browse → select a git repo from the filesystem (manual path entry supported)
4. Recent → previously used repos
5. Select a repo, then choose a branch (default: main)
6. Click Continue
7. What would you like to work on? screen:
8. Select an agent (Opencode, Claude Code, Codex, Gemini, Amp, Qwen Code, Copilot, Droid, Cursor Agent)
9. Enter a task description (Markdown supported)
10. Select a mode (Default, Build, etc.)
11. 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