vibekanban

What this skill does

# Vibe Kanban

Orchestration platform for AI coding agents. Plan, review, and manage AI-generated code in isolated git worktrees.

## Links

- [Documentation](https://www.vibekanban.com/docs)
- [Releases](https://github.com/BloopAI/vibe-kanban/releases)
- [GitHub](https://github.com/BloopAI/vibe-kanban)

## Quick Navigation

| Topic                         | Reference                                               |
| ----------------------------- | ------------------------------------------------------- |
| Installation & Setup          | [getting-started.md](references/getting-started.md)     |
| **Workspaces (Beta)**         | [workspaces.md](references/workspaces.md)               |
| Projects, Tasks, Review       | [core-features.md](references/core-features.md)         |
| Subtasks, Attempts, Conflicts | [advanced-features.md](references/advanced-features.md) |
| Settings, Agents, Tags        | [configuration.md](references/configuration.md)         |
| GitHub, Azure, VSCode, MCP    | [integrations.md](references/integrations.md)           |
| Common Issues                 | [troubleshooting.md](references/troubleshooting.md)     |
| Best Practices                | [vibe-guide.md](references/vibe-guide.md)               |

## Quick Start

### Install & Run

```bash
npx vibe-kanban
```

`npx vibe-kanban` remains the canonical cross-platform launch path. As of v0.1.30, the packaged desktop app is moving onto a Tauri v2 shell with built-in auto-update behavior for installed desktop builds.

## Release Highlights (0.1.15 → 0.1.28)

- MCP server expanded: richer issue retrieval (`get_issue` includes tags/relationships/sub-issues) and new workspace/relationship/tag tools (e.g. `update_workspace`, relationship + tag mutations).
- Frontend routing migrated to TanStack Router (navigation/URLs may differ from older screenshots).
- Reliability improvements around Electric fallback and cancellation/tab-switch handling.
- Review/diff UI improvements (annotation width fixes for horizontal scrolling).
- Remote Access: pair a host via a code and access its workspaces from another device.
- Workspace actions became safer around spin-off/duplicate flows by preserving branch and executor configuration more reliably.
- Active agent runs can now accept image attachments, which is useful when feeding UI state, screenshots, or design feedback back into an in-progress session.
- Transport reliability improvements: better relay disconnect handling and signing-session refresh.
- Claude: bumped the default Sonnet model to 4.6.
- Worktrees: preserve worktree path across cleanup to maintain Claude Code session continuity.
- Workspaces: improved workspace logs capture (root execution-process provider).
- Mobile UI fixes and Remote Access docs refresh.

## Release Highlights (0.1.44)

- Claude Code CLI pin moved forward again and the Codex executor surface was refreshed around Codex `0.124.0`.
- Legacy project routes are being sunset to an export-only page, so deep links or screenshots from older project pages may no longer match the current UX.
- Execution logs are pre-registered before normalized streaming begins, which improves log availability during live runs.
- Model selector ordering is now alphabetical, which changes some small but visible operator workflows in setup/review dialogs.

## Release Highlights (0.1.37 → 0.1.43)

- Executor surface refreshed with newer pinned versions for Codex, OpenCode, and Claude Code.
- Claude Code adds an `xhigh effort` variant.
- Cross-compile/runtime fixes improve Windows/MSVC and musl build reliability.

## Release Highlights (0.1.31 → 0.1.32)

- Desktop/Tauri: Windows desktop app support lands, Tauri notifications are available, and desktop zoom behavior is reworked around font-size scaling.
- Workspaces: sessions can be renamed and auto-named; draft workspace-creation preference is persisted.
- Attachments: arbitrary attachments are supported across workspaces and issues.
- MCP: issue filters are available through the MCP surface.
- Remote/admin: remote audit logging is added, short issue IDs become org-scoped, and analytics are disabled when PostHog config is blank.
- Editor UX: WYSIWYG typeahead, toolbar, and issue-description editing flows are improved.

Opens browser automatically. Use `PORT=8080 npx vibe-kanban` for fixed port.

### Prerequisites

- Node.js LTS
- Authenticated coding agent (Claude Code, Codex, Gemini, etc.)
- GitHub CLI (`gh`) for PR integration

### First Steps

1. Authenticate with a coding agent externally
2. Run `npx vibe-kanban`
3. Complete setup dialogs
4. Create project from existing git repo
5. Add tasks and start executing

## Two UI Modes

### Classic Kanban (Tasks)

Traditional board with columns: To do → In Progress → In Review → Done

Updates in v0.1.7:

- Per-project Kanban views and a refreshed filter dialog
- Sub-issues and Workspaces visibility toggles moved to the filter bar

### Workspaces (Beta) — NEW

Modern interface with:

- **Sessions**: Multiple conversation threads per workspace
- **Command Bar**: `Cmd/Ctrl + K` for all actions
- **Workspace Notes**: Document requirements and decisions
- **Multi-repo support**: Work across multiple repositories
- **Integrated Terminal**: PTY-backed terminal with shell support
- **Session Dropdown**: Agent icons displayed next to session titles
- **Sidebar filters**: Filter by project and PR status (including “No project”)
- **Needs Attention**: Includes workspaces with unseen activity

Switch between modes via Command Bar → "Open in Old UI"

## Core Concepts

### Git Worktrees

Each task/workspace runs in an **isolated git worktree**:

- Agents can't interfere with each other
- Safe from main branch changes
- Automatic cleanup after completion

### Task Flow (Classic)

```
To do → In Progress → In Review → Done
```

- **To do**: Task created
- **In Progress**: Agent executing
- **In Review**: Agent finished, awaiting review
- **Done**: Merged or PR merged

### Task Attempts

One task can have multiple attempts:

- Different agent
- Different branch
- Fresh conversation context

## Supported Agents

| Agent          | Variants                     |
| -------------- | ---------------------------- |
| Claude Code    | DEFAULT, PLAN, ROUTER, XHIGH |
| Codex          | DEFAULT, HIGH                |
| Gemini         | DEFAULT, FLASH               |
| GitHub Copilot | DEFAULT                      |
| Amp            | DEFAULT                      |
| Cursor Agent   | DEFAULT                      |
| OpenCode       | DEFAULT                      |
| Qwen Code      | DEFAULT                      |
| Droid          | DEFAULT                      |
| Antigravity    | DEFAULT                      |

Select agent when creating task attempt or workspace session.

## Project Configuration

### Setup Scripts

Run before agent execution (e.g., `npm install`, `cargo build`).

### Dev Server Scripts

Start dev server for preview (e.g., `npm run dev`).

### Cleanup Scripts

Run after agent finishes (e.g., `npm run format`).

### Copy Files

Files to copy from main project to worktree (e.g., `.env`).

## Task Creation

```
Press C or click + to create task
```

Options:

- **Create Task**: Add to board only
- **Create & Start**: Add and immediately execute with default agent

### Task Tags

Reusable snippets via `@mention`:

- Type `@` in description
- Select tag from dropdown
- Content inserted at cursor

Task description editor supports markdown paste and preserves inline code formatting.

## Code Review

1. Task moves to "In Review" when agent finishes
2. Click Diff icon to view changes
3. Click `+` on any line to add comment
4. Submit all comments together
5. Task returns to "In Progress" for fixes

## Git Operations

| Action    | Description                       |
| --------- | --------------------------------- |
| Merge     | Merge to target branch            |
| Create PR | Open PR on GitHub/Azure           |
| Rebase    | Update with target branch changes |