vibe-kanban

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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)

平台	当前支持	要求
Claude	原生MCP集成	在 `mcpServers` 中注册
Codex	MCP脚本集成	运行 `scripts/mcp-setup.sh --codex` 或进行等效配置
Gemini	MCP注册	配置 `mcpServers` /桥接服务
OpenCode	MCP/桥接集成	完成 `omx` / `ohmg` 或等效设置

是否仅需本技能即可使用：

Claude/Gemini: 是
Codex: 是（需要基于脚本完成设置）
OpenCode: 是（通过编排实现）

Vibe Kanban — AI Agent Kanban Board

Vibe Kanban — AI Agent 看板

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.

从单一看板管理多个AI Agent（Claude/Codex/Gemini）。将卡片（任务）移动到「进行中」状态时会自动创建git worktree并启动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

当你需要将一个史诗任务拆分为独立任务分配给并行Agent时
当你需要可视化追踪AI正在进行的工作状态时
当你需要在UI中以diff/日志的形式审核Agent结果并重试任务时
当你需要将基于GitHub PR的团队协作与AI Agent工作流程结合时

Prerequisites

前置要求

bash

undefined

bash

undefined

Node.js 18+ required

需要Node.js 18+版本

node --version

Complete agent authentication beforehand

提前完成Agent身份认证

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

---

claude --version # 配置ANTHROPIC_API_KEY codex --version # 配置OPENAI_API_KEY（可选） gemini --version # 配置GOOGLE_API_KEY（可选） opencode --version # 无需单独配置（基于GUI的内置认证）


> **已验证版本（截至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)

npx（最快方式）

bash

undefined

bash

undefined

Run immediately (no installation needed)

直接运行（无需安装）

npx vibe-kanban

Specify port (default port 3000)

指定端口（默认端口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...

undefined

bash scripts/vibe-kanban-start.sh


浏览器会自动打开`http://localhost:3000`。

> ⚠️ **端口冲突警告**: 如果其他开发服务（如Next.js）正在使用3000端口，
> 请运行`PORT=3001 npx vibe-kanban --port 3001`。
> 确认启动日志中显示`Main server on :3001`后，访问`http://localhost:3001`即可。

正常启动日志示例:

undefined

Clone + dev mode

克隆仓库 + 开发模式

bash

git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban
pnpm i
pnpm run dev

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)

变量	说明	默认值
`PORT`	服务端口	`3000`
`HOST`	服务host	`127.0.0.1`
`VIBE_KANBAN_REMOTE`	允许远程连接	`false`
`VK_ALLOWED_ORIGINS`	CORS允许的来源	未设置
`DISABLE_WORKTREE_CLEANUP`	禁用worktree清理	未设置
`ANTHROPIC_API_KEY`	Claude Code Agent使用	—
`OPENAI_API_KEY`	Codex/GPT Agent使用	—
`GOOGLE_API_KEY`	Gemini Agent使用	—

启动服务前在

.env

文件中配置即可。

各Agent的API密钥配置位置（设置 → Agent → 环境变量）
Claude Code:
ANTHROPIC_API_KEY
Codex:
OPENAI_API_KEY
Gemini:
GOOGLE_API_KEY
Opencode: 无需单独配置（内置认证）

MCP Configuration

MCP配置

Vibe Kanban runs as an MCP (Model Context Protocol) server, letting agents control the board directly.

Vibe Kanban作为MCP（模型上下文协议）服务器运行，允许Agent直接控制看板。

Claude Code MCP Setup

Claude Code MCP设置

~/.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"
      }
    }
  }
}

配置

~/.claude/settings.json

或项目级

.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

OpenCode MCP设置

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.

添加到

~/.config/opencode/opencode.json

json

{
  "mcp": {
    "vibe-kanban": {
      "command": "npx",
      "args": ["vibe-kanban", "--mcp"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "3001"
      }
    }
  }
}

重启后，

vk_*

工具可以直接在你的OpenCode会话中使用。

MCP Tool List

MCP工具列表

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.

工具	说明
`vk_list_cards`	列出所有卡片（工作空间）
`vk_create_card`	创建新卡片
`vk_move_card`	修改卡片状态
`vk_get_diff`	获取卡片diff
`vk_retry_card`	重新运行卡片任务

⚠️ 旧版本工具名称变更:
vk_list_tasks
→
vk_list_cards
,
vk_create_task
→
vk_create_card
以上是v0.1.17版本MCP API的官方确认工具名称。

Codex MCP Integration

Codex MCP集成

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.

要将Vibe Kanban与Codex连接，在项目根目录运行以下命令:

bash

bash scripts/mcp-setup.sh --codex

该命令会将

vibe-kanban

MCP服务配置添加到

~/.codex/config.toml

中。基于钩子的自动循环不是Codex的默认行为，因此重试/循环管理通过看板卡片进度状态或上层编排器处理。

Workspace → Parallel Agents → PR Workflow

工作空间 → 并行Agent → PR工作流

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.

v0.1.17实际UI结构: Vibe Kanban是一个看板，但实际的工作单元是工作空间。每个工作空间独立处理一个任务。

1. Start the server

1. 启动服务

bash

undefined

bash

undefined

Default run

默认运行

npx vibe-kanban

→ http://localhost:3000

→ 访问http://localhost:3000

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

端口冲突时（比如运行了Next.js）

PORT=3001 npx vibe-kanban --port 3001

→ http://localhost:3001

→ 访问http://localhost:3001

undefined

undefined

2. (Optional) Review epic plan with planno

2.（可选）使用planno审核史诗计划

text

Review the implementation plan for this feature with planno

planno (plannotator) is an independent skill — usable without Vibe Kanban.

text

使用planno审核该功能的实现计划

planno（plannotator）是独立技能，无需Vibe Kanban即可使用。

3. Create a Workspace

3. 创建工作空间

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

打开UI → 点击**"+ 创建工作空间"**或左侧边栏的
```
+
```
按钮
选择仓库页面:
- 浏览 → 从文件系统选择git仓库（支持手动输入路径）
- 最近使用 → 之前使用过的仓库
- 选择仓库后，选择分支（默认:
```
main
```
  ）
- 点击继续
输入工作内容页面:
- 选择Agent（Opencode、Claude Code、Codex、Gemini、Amp、Qwen Code、Copilot、Droid、Cursor Agent）
- 输入任务描述（支持Markdown）
- 选择模式（默认、构建等）
- 点击创建

4. Automatic agent execution

4. 自动执行Agent任务

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

工作空间创建后:

自动创建

vk/<hash>-<slug>

分支（例如

vk/3816-add-a-comment-to

）

自动创建git worktree（每个Agent完全隔离）
运行选中的Agent CLI并流式输出日志

工作空间状态:

运行中: Agent正在执行（显示在左侧边栏）
空闲: 等待分配任务
需要关注: Agent执行完成或需要人工输入

5. Review results

5. 审核结果

Changes panel: View file diffs
Logs panel: Agent execution logs
Preview panel: Web app preview
Terminal: Run commands directly
Notes: Write notes

变更面板: 查看文件diff
日志面板: Agent执行日志
预览面板: Web应用预览
终端: 直接运行命令
笔记: 编写备注

6. Create PR & finish

6. 创建PR并完成任务

Workspace detail → "Open pull request" button
PR merge → workspace moves to Archive
Worktree cleaned up automatically

工作空间详情页 → **"创建拉取请求"**按钮
PR合并后 → 工作空间移动到归档
自动清理worktree

Git Worktree Isolation Structure

Git Worktree隔离结构

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/

工作空间目录（可在设置 → 通用 → 工作空间目录中配置）:

~/.vibe-kanban-workspaces/          ← 默认位置（家目录下）
├── <workspace-uuid-1>/             ← 工作空间1隔离环境
├── <workspace-uuid-2>/             ← 工作空间2隔离环境
└── <workspace-uuid-3>/             ← 工作空间3隔离环境

分支命名规则（可在设置 → 通用 → Git → 分支前缀中配置）:

vk/<4位ID>-<任务slug>
例如: vk/3816-add-a-comment-to-readme

内部执行逻辑:

bash

git worktree add <workspace-dir> -b vk/<hash>-<task-slug> main
<agent-cli> -p "<task-description>" --cwd <workspace-dir>

推荐的.gitignore配置:
.vibe-kanban-workspaces/
.vibe-kanban/

Remote Deployment

远程部署

Docker

bash

undefined

bash

undefined

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

undefined

docker run -p 3000:3000
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
-e VK_ALLOWED_ORIGINS=https://vk.example.com
vibekanban/vibe-kanban

undefined

Reverse Proxy (Nginx/Caddy)

反向代理（Nginx/Caddy）

bash

undefined

bash

undefined

CORS must be allowed

必须允许CORS

VK_ALLOWED_ORIGINS=https://vk.example.com

Or multiple origins

或者配置多个来源

VK_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com

undefined

VK_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com

undefined

SSH Remote Access

SSH远程访问

Integrates with VSCode Remote-SSH:

vscode://vscode-remote/ssh-remote+user@host/path/to/.vk/trees/<task-slug>

支持VSCode Remote-SSH集成:

vscode://vscode-remote/ssh-remote+user@host/path/to/.vk/trees/<task-slug>

Troubleshooting

故障排查

Worktree conflicts / orphaned worktrees

Worktree冲突/孤立worktree

bash

undefined

bash

undefined

Clean up orphaned worktrees

清理孤立worktree

git worktree prune

List current worktrees

列出当前所有worktree

git worktree list

Force remove a specific worktree

强制删除指定worktree

git worktree remove .vk/trees/<slug> --force

undefined

git worktree remove .vk/trees/<slug> --force

undefined

403 Forbidden (CORS error)

403禁止访问（CORS错误）

bash

undefined

bash

undefined

CORS config required for remote access

远程访问需要配置CORS

VK_ALLOWED_ORIGINS=https://your-domain.com npx vibe-kanban

undefined

VK_ALLOWED_ORIGINS=https://your-domain.com npx vibe-kanban

undefined

Agent won't start

Agent无法启动

bash

undefined

bash

undefined

Test CLI directly

直接测试CLI是否可用

claude --version codex --version

Check API keys

检查API密钥配置

echo $ANTHROPIC_API_KEY echo $OPENAI_API_KEY

undefined

echo $ANTHROPIC_API_KEY echo $OPENAI_API_KEY

undefined

Port conflict

端口冲突

bash

undefined

bash

undefined

Use a different port

使用其他端口

npx vibe-kanban --port 3001

Or use environment variable

或者使用环境变量指定

PORT=3001 npx vibe-kanban

undefined

PORT=3001 npx vibe-kanban

undefined

SQLite lock error

SQLite锁错误

bash

undefined

bash

undefined

Disable worktree cleanup and restart

禁用worktree清理后重启服务

DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban

---

DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban

---

UI vs CLI Decision Guide

UI与CLI选择指南

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

场景	模式
团队共享看板、可视化进度追踪	UI（ `npx vibe-kanban` ）
CI/CD流水线、脚本自动化	CLI（ `scripts/pipeline.sh` ）
快速本地实验	CLI（ `scripts/conductor.sh` ）
浏览器端diff/日志审核	UI

Supported Agents (verified v0.1.17)

支持的Agent（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

在设置 → Agent中配置每个Agent:

Agent	命令	API密钥
Opencode	`opencode`	内置（默认）
Claude Code	`claude`	`ANTHROPIC_API_KEY`
Codex	`codex`	`OPENAI_API_KEY`
Gemini	`gemini`	`GOOGLE_API_KEY`
Amp	`amp`	单独配置
Qwen Code	`qwen-coder`	单独配置
Copilot	`copilot`	GitHub账号
Droid	`droid`	单独配置
Cursor Agent	`cursor`	Cursor订阅

每个Agent可配置项:

追加提示词: Agent运行时追加的额外指令
模型: 使用的模型名称（例如
```
claude-opus-4-6
```
）
变体: 模型变体
自动批准: 自动批准Agent操作（默认: 开启）
自动压缩: 自动压缩上下文（默认: 开启）
环境变量: API密钥和其他环境变量

Representative Use Cases

典型用例

1. Parallel epic decomposition

1. 并行史诗任务拆分

"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

"支付流程v2"史诗任务
  ├── 工作空间1: 前端UI  → Claude Code
  ├── 工作空间2: 后端API  → Codex
  └── 工作空间3: 集成测试 → Opencode
→ 3个工作空间同时运行 → 并行实现

2. Role-based specialist agent assignment

2. 基于角色的专业Agent分配

Claude Code  → design/domain-heavy features
Codex        → types/tests/refactoring
Gemini       → docs/storybook writing
Opencode     → general tasks (default)

Claude Code  → 设计/领域相关复杂功能
Codex        → 类型/测试/重构
Gemini       → 文档/storybook编写
Opencode     → 通用任务（默认）

3. GitHub PR-based team collaboration

3. 基于GitHub PR的团队协作

Set VIBE_KANBAN_REMOTE=true
→ Team members check status on the board
→ Review/approval only via GitHub PR
→ Parallel agents + traditional PR process combined

设置VIBE_KANBAN_REMOTE=true
→ 团队成员在看板上查看状态
→ 仅通过GitHub PR进行审核/批准
→ 并行Agent + 传统PR流程结合

4. Implementation comparison

4. 实现方案对比

Same task, two workspaces:
  Workspace A → Claude Code (UI structure focus)
  Workspace B → Codex (performance optimization focus)
→ Compare PRs, pick best-of-both

同一个任务，创建两个工作空间:
  工作空间A → Claude Code（侧重UI结构）
  工作空间B → Codex（侧重性能优化）
→ 对比PR，选择最优方案合并

5. OpenCode + ulw parallel delegation

5. OpenCode + ulw并行任务分配

Combine with OpenCode's ulw (ultrawork) mode to run agents in parallel at the epic level:

python

undefined

与OpenCode的ulw（ultrawork）模式结合，在史诗任务层级并行运行Agent:

python

undefined

ulw keyword → activates ultrawork parallel execution layer

ulw关键词 → 激活ultrawork并行执行层

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

Vibe Kanban看板: 另开终端运行npx vibe-kanban

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

task(category="visual-engineering", run_in_background=True, load_skills=["frontend-ui-ux", "vibe-kanban"], description="[Kanban WS1] 前端UI", prompt="实现支付流程UI — src/components/payment/下的卡输入、订单确认、完成页面")

task(category="unspecified-high", run_in_background=True, load_skills=["vibe-kanban"], description="[Kanban WS2] 后端API", prompt="实现支付流程API — POST /charge、POST /refund、GET /status/:id")

task(category="unspecified-low", run_in_background=True, load_skills=["vibe-kanban"], description="[Kanban WS3] 集成测试", prompt="编写支付E2E测试 — 成功/失败/退款场景")

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

→ 3个工作空间同时出现在看板的运行中状态

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

→ 每个任务完成后: 需要关注 → 创建PR → 归档

---

---

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

保持卡片范围精简（1个卡片 = 1个提交单元）
对于跨2个以上文件的变更，先使用planno审核计划
仅在可信网络中开启
```
VIBE_KANBAN_REMOTE=true
```
如果Agent运行卡住，重新分配任务或拆分卡片

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│
   └─────────┘        └───────────┘       └─────────┘

┌─────────────────────────────────────────────────────────┐
│                    Vibe Kanban UI                       │
│   ┌──────────┬──────────┬──────────┬──────────┐        │
│   │  待办   │ 进行中  │  审核  │   完成   │        │
│   └──────────┴──────────┴──────────┴──────────┘        │
└───────────────────────────┬─────────────────────────────┘
                            │ REST API
┌───────────────────────────▼─────────────────────────────┐
│                    Rust 后端                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │
│  │ 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

.agent-skills/vibe-kanban/
├── SKILL.md              # 主技能文档
├── SKILL.toon            # TOON格式（压缩版）
├── scripts/
│   ├── start.sh          # 服务启动封装脚本
│   ├── cleanup.sh        # Worktree清理脚本
│   ├── mcp-setup.sh      # MCP设置自动化脚本
│   └── health-check.sh   # 服务健康检查脚本
├── references/
│   ├── environment-variables.md  # 环境变量参考
│   └── mcp-api.md                # MCP API参考
└── templates/
    ├── claude-mcp-config.json    # Claude Code MCP配置模板
    ├── docker-compose.yml        # Docker部署模板
    └── .env.example              # 环境变量示例

Script Usage

脚本使用说明

bash

undefined

bash

undefined

Start server

启动服务

bash scripts/start.sh --port 3001

Worktree cleanup

Worktree清理

bash scripts/cleanup.sh --dry-run # Preview bash scripts/cleanup.sh --all # Remove all VK worktrees

bash scripts/cleanup.sh --dry-run # 预览清理内容 bash scripts/cleanup.sh --all # 移除所有VK worktree

MCP setup

MCP设置

bash scripts/mcp-setup.sh --claude # Claude Code setup bash scripts/mcp-setup.sh --all # Setup for all agents

bash scripts/mcp-setup.sh --claude # 配置Claude Code bash scripts/mcp-setup.sh --all # 配置所有Agent

Health check

健康检查

bash scripts/health-check.sh bash scripts/health-check.sh --json # JSON output

---

bash scripts/health-check.sh bash scripts/health-check.sh --json # JSON格式输出

---

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

=== 启动服务 ===
npx vibe-kanban                       直接运行（端口3000）
PORT=3001 npx vibe-kanban --port 3001 端口冲突时使用（比如运行了Next.js）
http://localhost:3000                  看板UI地址

=== 环境变量 ===
PORT=3001                        修改端口
VK_ALLOWED_ORIGINS=https://...   允许CORS来源
ANTHROPIC_API_KEY=...            Claude Code认证
OPENAI_API_KEY=...               Codex认证
GOOGLE_API_KEY=...               Gemini认证

=== MCP集成 ===
npx vibe-kanban --mcp            MCP模式
vk_list_cards                    列出卡片（工作空间）
vk_create_card                   创建卡片
vk_move_card                     修改状态

=== 工作空间流程 ===
创建 → 运行中 → 需要关注 → 归档
运行中: worktree已创建 + Agent已启动
需要关注: 执行完成或需要人工输入
归档: PR合并完成

=== MCP配置文件位置 ===
Opencode: ~/.config/opencode/opencode.json
Claude Code: ~/.claude/settings.json 或 .mcp.json

=== worktree清理 ===
git worktree prune               清理孤立worktree
git worktree list                列出所有worktree
git worktree remove <path>       强制删除指定worktree