vibe-kanban

What this skill does

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

1. Open the UI → click **"+ Create Workspace"** or the `+` button in the left sidebar
2. **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**
3. **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:
```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_A