Vibekanban

Vibe Kanban

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

Links

• Documentation
• Releases
• GitHub

Quick Navigation

Quick Start

Install & Run

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

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

Preview Mode

Test web apps without leaving Vibe Kanban:

1. Configure dev server script in project settings 2. Click "Start Dev Server" in Preview tab 3. View app in embedded iframe 4. Install vibe-kanban-web-companion for component selection

Keyboard Shortcuts

MCP Integration

Add MCP Servers to Agents

Settings → MCP Servers → Select agent → Add servers

Vibe Kanban MCP Server

Expose Vibe Kanban to external MCP clients:

{
  "mcpServers": {
    "vibe_kanban": {
      "command": "npx",
      "args": ["-y", "vibe-kanban@latest", "--mcp"]
    }
  }
}

MCP tools include: list_workspaces, update_workspace, list_projects, list_issues, get_issue, update_issue, plus tag and relationship helpers.

Critical Safety Note

Vibe Kanban runs agents with --dangerously-skip-permissions/--yolo by default for autonomous operation. Each task runs in isolated worktree, but agents can still perform system-level actions. Review work and keep backups.

Critical Prohibitions

• Do not skip agent authentication before first use
• Do not ignore worktree isolation benefits
• Do not forget to configure setup/cleanup scripts for dependencies
• Do not mix multiple agents on same task without new attempts
• Do not ignore rebase conflicts — resolve or abort

Links

• Documentation
• Releases
• GitHub
• Vibe Guide

Advanced Features

Subtasks, new task attempts, and resolving rebase conflicts.

Creating Subtasks

Break complex tasks into smaller pieces.

How to Create

1. Open task attempt 2. Click triple dot icon (top right) 3. Select "Create Subtask" 4. Fill in title/description 5. Save

Subtask inherits base branch from parent attempt.

Subtask Behavior

• Linked to specific task attempt, not just task
• Appears as regular task on kanban board
• Own lifecycle: To do → In Progress → In Review → Done
• Can have own attempts and agents
• Can create nested subtasks

Viewing Relationships

Parent task shows:

• Child Tasks section with count
• Links to each subtask

Subtask shows:

• Parent Task section
• Link to parent
• Unlink action available when context allows (v0.1.7)

New Task Attempts

Multiple attempts per task for fresh restarts.

When to Create

• First approach didn't work
• Want different agent (Claude → Codex)
• Need different variant (DEFAULT → PLAN)
• Different base branch
• Reset conversation context

Tip: Most tasks need only one attempt.

How to Create

1. Open task 2. Click triple dot icon 3. Select "Create New Attempt" 4. Configure agent, variant, branch 5. Click "Create Attempt"

Impact on Subtasks

Subtasks linked to original attempt remain unchanged. New subtasks from new attempt use new attempt's branch.

Resolving Rebase Conflicts

When your branch conflicts with target branch after rebase.

Conflict Banner Options

Automatic Resolution (Recommended)

1. Click "Resolve Conflicts" 2. Instructions generated in follow-up field 3. Review instructions 4. Click "Resolve Conflicts" (Send button changes) 5. Agent resolves conflicts

Manual Resolution

Single files:

• Click "Open in Editor" from banner
• Edit one file at a time
• Refresh page for next file

Multiple files (recommended):

• Click triple dot → "Open in [Your IDE]"
• Opens entire worktree
• Resolve all conflicts
• Run:

git add .
git rebase --continue

Merge Markers

<<<<<<< HEAD (your changes)
function newFeature() {
  return "new implementation";
}
=======
function oldFeature() {
  return "existing implementation";
}
>>>>>>> main (base branch changes)

Rebasing onto Different Branch

If task was created from wrong branch:

1. Change base branch in task settings 2. See commits from old branch that shouldn't be there 3. Use:

git rebase <last-commit-before-your-work> --onto <new-base>

Warning: Identify correct commit hash. Consider backup branch first.

Aborting

Click "Abort Rebase" to return to "Rebase needed" state. Can try again or create new attempt from updated branch.

Configuration & Customisation

Global settings, agent profiles, task tags, and keyboard shortcuts.

Supported Agents

Variant Meanings

Claude Code: DEFAULT (standard), PLAN (plan → confirm → execute), ROUTER (agentic routing)

Codex: DEFAULT (standard), HIGH (high-effort mode), default model: gpt-5.2-codex

Gemini: DEFAULT (standard), FLASH (fast mode)

Executor refresh (v0.1.44)

• The 0.1.44 line refreshes the Codex executor surface and bumps the pinned Claude Code CLI version again.
• If you override executor base commands or depend on specific CLI flags, re-test those overrides after upgrade instead of assuming the old executor contract still applies.
• Model lists in the selector are now sorted alphabetically, so setup/review flows may feel slightly different even when the underlying config is unchanged.

Workspace Executor Config (v0.1.15)

• Workspace create flow now uses executor_config more consistently.
• Default fallback handling was fixed to reduce incorrect executor defaults in new workspaces.

Best Practice: Use biggest/most capable model — fewer mistakes, less intervention.

Global Settings

Access: Settings page (⚙️ icon in sidebar)

Remote Access (v0.1.21)

Remote Access is configured from the Settings page:

1. On the host machine: Settings → Remote Access → generate a pairing code. 2. On the client device: sign in at https://cloud.vibekanban.com → Remote Access → link the host with the pairing code.

Once linked, you can browse and open the host's workspaces remotely.

Themes

Light / Dark mode toggle.

Default Agent Configuration

Pre-selected agent and variant for new attempts.

1. Select agent (Claude Code, Gemini, Codex, etc.) 2. Choose variant (DEFAULT, PLAN, etc.)

Override per-attempt in create dialog.

Editor Integration

Supported editors:

• VS Code
• VS Code Insiders
• Cursor
• Windsurf
• Neovim, Emacs, Sublime Text
• Custom shell command

Remote SSH Configuration

For Vibe Kanban running on remote server:

Enables vscode://vscode-remote/ssh-remote+user@host/path URLs.

Prerequisites:

• SSH keys configured (no password prompts)
• VSCode Remote-SSH extension installed

Git Configuration

Branch Prefix: Prefix for auto-generated branches (e.g., vk → vk/task-name)

Notifications

Toggle sound effects and push notifications.

Telemetry

Enable/disable data collection.

Agent Profiles & Configuration

Settings → Agents

Define multiple variants per agent with different configurations.

Configuration Access

• Form Editor: Guided interface
• JSON Editor: Direct JSON editing

Configuration Structure

{
  "executors": {
    "CLAUDE_CODE": {
      "DEFAULT": { "CLAUDE_CODE": { "dangerously_skip_permissions": true } },
      "PLAN": { "CLAUDE_CODE": { "plan": true } },
      "ROUTER": { "CLAUDE_CODE": { "claude_code_router": true, "dangerously_skip_permissions": true } }
    },
    "GEMINI": {
      "DEFAULT": { "GEMINI": { "model": "default", "yolo": true } },
      "FLASH": { "GEMINI": { "model": "flash", "yolo": true } }
    },
    "CODEX": {
      "DEFAULT": { "CODEX": { "sandbox": "danger-full-access" } },
      "HIGH": { "CODEX": { "sandbox": "danger-full-access", "model_reasoning_effort": "high" } }
    }
  }
}

Agent-Specific Options

Claude Code:

• plan: Planning mode
• claude_code_router: Route across instances
• dangerously_skip_permissions: Skip prompts

Universal Options:

• append_prompt: Text appended to system prompt
• base_command_override: Override CLI command
• additional_params: Extra CLI arguments

Warning: Options with "dangerously\_" bypass safety confirmations.

Task Tags

Reusable text snippets inserted via @mention.

Managing Tags

Settings → General → Task Tags

• Add Tag: Click "Add Tag"
• Edit: Click edit icon (✏️)
• Delete: Click delete icon (🗑️)

Naming

Use snake_case (no spaces): bug_report, feature_request, code_review_checklist

Using Tags

1. Type @ in task description 2. Filter by typing 3. Select tag or press Enter 4. Content inserted at cursor

Works in task descriptions and follow-up messages.

Common Use Cases

• Bug report templates
• Acceptance criteria checklists
• Code review guidelines

Keyboard Shortcuts

Platform Keys

• ⌘ = Mac Command
• Ctrl = Windows/Linux Control

Global Shortcuts

Board Navigation

(When task card has blue focus ring)

Forms & Dialogs

Tips

• Blue focus ring indicates active navigation
• Global shortcuts disabled in text fields
• ⌘S badge shown near search field

Core Features

Projects, tasks, execution monitoring, testing, code review, and task completion.

Creating Projects

Project route change (v0.1.44)

Legacy project routes are being sunset to an export-only page. If older docs, bookmarks, or teammate screenshots point at project-specific pages that no longer behave the same way, treat that as expected product drift rather than a broken local install.

From Existing Repository

1. Click "Create Project" 2. Select "From existing git repository" 3. Browse and select git repo

Create Blank

1. Click "Create Project" 2. Select "Create blank project" 3. New git repo generated

Project Settings

Access via settings button (top right) after creating project.

Important: Setup scripts ensure dependencies exist in worktree. Cleanup scripts act like pre-commit hooks.

Warning: Ensure copied files are gitignored to avoid accidental commits.

Creating Tasks

Press C or click + icon.

Options

• Create Task: Add to board only
• Create & Start: Add + immediately execute with default agent

Task Fields

• Title (required)
• Description (optional, supports markdown; paste preserves inline code and supports raw paste)
• Base branch (defaults to configured target branch)

Description editing UX was refined in v0.1.31 with better typeahead priority and toolbar behavior in the WYSIWYG editor.

Task Tags

Reusable text snippets via @mention:

1. Type @ in description 2. Filter by typing tag name 3. Select tag → content inserted

Manage tags: Settings → General → Task Tags

Issue Attachments (v0.1.13)

• Image attachments are supported on issues.
• Use inline attachments in descriptions/comments; attachment handling is proxied by the server (ensure proxy routes are enabled for self-hosting).

Expanded Attachments (v0.1.32)

• Attachments are no longer limited to images; arbitrary files are supported across issues and workspace flows.
• This is useful when a task needs logs, archives, specs, or other non-image artifacts attached directly to the working context.

Task Columns

Kanban Filters (v0.1.7)

• Per-project Kanban views for tailored boards
• Filter dialog refreshed for faster selection
• Sub-issues and Workspaces visibility toggles moved into the filter bar

Starting Tasks

1. Open task without attempts 2. Click + to create attempt 3. Configure:

• Agent profile: Claude Code, Gemini, Codex, etc.
• Variant: DEFAULT, PLAN, etc.
• Base branch: Branch to work from

Monitoring Execution

Execution Flow

1. Setup Script runs (if configured) 2. Task sent to agent (title + description) 3. Real-time actions displayed:

• Reasoning
• Commands
• File operations
• Tool usage

4. Action approvals (Codex; Claude Code coming soon) 5. Cleanup Script runs 6. Commit generated (auto-message from agent's last message)

Execution log reliability (v0.1.44)

• Execution log stores are now pre-registered before normalized log streaming starts.
• If you rely on live process inspection, this release reduces the chance of early-run logs appearing missing purely because the store was registered too late.

Interaction During Execution

Image Attachments During Active Runs (v0.1.28)

• You can attach images while the agent is still running instead of waiting for the run to finish.
• This is useful for UI review, visual bug reports, screenshots, and annotated design feedback that should immediately influence the current attempt.

Edit Previous Messages

Supported by: Claude Code, Amp, Codex, Gemini, Qwen

Warning: Editing reverts all subsequent agent work.

Testing Your Application

Preview Mode — embedded browser for web apps.

Setup

1. Configure dev server script in project settings 2. Install Web Companion (optional, for component selection):

npm install vibe-kanban-web-companion

Add to app:

import { VibeKanbanWebCompanion } from 'vibe-kanban-web-companion';

// In React root
<VibeKanbanWebCompanion />
<App />

Using Preview

1. Click "Start Dev Server" in Preview tab 2. App loads in iframe 3. Dev server logs shown at bottom 4. Toolbar: Refresh, Copy URL, Open in Browser, Stop

Component Selection

With Web Companion installed:

1. Click floating Vibe Kanban button 2. Click component to select 3. Choose depth (inner/outer) 4. Add follow-up message — agent knows exactly which component

Reviewing Code Changes

1. Task moves to "In Review" when agent finishes 2. Click Diff icon to view changes 3. Click + on line to add comment 4. Write feedback 5. Click Send to submit all comments 6. Task returns to "In Progress"

Comments sent as single message to agent.

Completing a Task

Git Operations Header

Shows:

• Task branch
• Target branch (with change option)
• Commits ahead/behind

Actions

Guardrails: Merge actions are disabled when an open PR exists or when the target is remote-only.

Rebase dialog reflects the current target branch; verify it before rebasing.

Pull Request Flow

1. Click "Create PR" 2. Title/description pre-filled from task (and now can be prefilled from initial prompt context) 3. After creation, button becomes "Push" (disabled until new changes) 4. When PR merged on GitHub, task auto-moves to Done

Core Object Reliability (v0.1.15)

• Kanban core objects use Electric fallback and timeout-based failover.
• This reduces workspace/task flow disruptions during transient backend instability.

Getting Started

Installation and initial setup for Vibe Kanban.

Supported Systems

macOS (Intel/Apple Silicon), Linux, Windows

Prerequisites

1. Node.js: Latest LTS version 2. Coding Agent: Authenticate externally before using Vibe Kanban

Installation

npx vibe-kanban

• Binds to random free port
• Opens browser automatically
• This remains the default docs-first launch path even after the packaged desktop app moved to a Tauri v2 shell in v0.1.30.

Fixed Port

PORT=8080 npx vibe-kanban

Initial Setup Flow

1. Authenticate with coding agent — Do this externally first (e.g., claude auth login) 2. Run `npx vibe-kanban` — Application launches 3. Complete setup dialogs — Configure agent and editor preferences 4. Create first project — Select from recent git repos or create blank 5. Add tasks — Start tracking work

GitHub Integration (Optional)

Requires GitHub CLI:

brew install gh  # macOS
gh auth login

Enables: Creating PRs, PR status syncing, auto-move to Done when merged.

Updating

npx vibe-kanban@latest

• If you run the packaged desktop build rather than npx, expect updates to come through the app's Tauri v2 auto-updater path instead of the npm command above.

Integrations

GitHub, Azure Repos, VSCode Extension, and MCP servers.

GitHub Integration

Create PRs directly from tasks via GitHub CLI.

Setup

Automatic: Prompted when first creating PR on macOS (Homebrew install).

Manual:

# Install
brew install gh  # macOS
# Windows/Linux: See https://github.com/cli/cli#installation

# Authenticate
gh auth login

Creating a PR

1. Open task with changes 2. Click "Create PR" 3. Title/description pre-filled from task 4. Click "Create"

PR link added to task. When merged on GitHub, task auto-moves to Done.

Azure Repos Integration

Create PRs via Azure CLI with DevOps extension.

Setup

# Install Azure CLI
brew install azure-cli  # macOS

# Add DevOps extension
az extension add --name azure-devops

# Authenticate
az login

# Configure defaults (optional)
az devops configure --defaults organization=https://dev.azure.com/{your-org} project={your-project}

Supported URL Formats

• Modern: https://dev.azure.com/{org}/{project}/_git/{repo}
• Legacy: https://{org}.visualstudio.com/{project}/_git/{repo}

Both HTTPS and SSH remotes supported.

Creating a PR

Same flow as GitHub: Click "Create PR" in task view.

VSCode Extension

Task management directly in IDE.

Installation

VSCode: Install from Marketplace (bloop.vibe-kanban)

Cursor/Windsurf: Install from Open VSX Registry

Or search: @id:bloop.vibe-kanban

Features

Workflow

1. Start task in Vibe Kanban web UI 2. Click "Open in VSCode" (or Cursor/Windsurf) 3. IDE opens in task worktree 4. Extension populated with task context

Important: Extension only works when opened via Vibe Kanban — needs worktree context.

Supported IDEs

Desktop / Tauri Notes (v0.1.31 → v0.1.32)

• Windows desktop packaging is available through the Tauri app shell.
• Tauri builds can surface system notifications.
• If you are validating desktop behavior, note that zoom was reimplemented via font-size scaling in the Tauri app.

Connecting MCP Servers to Agents

Add external tools to coding agents.

Access

Settings → MCP Servers → Select agent

Popular Servers

One-click installation for common servers (Playwright, Sentry, Notion, etc.)

Custom Servers

Add to Server Configuration JSON:

{
  "mcpServers": {
    "my_custom_server": {
      "command": "node",
      "args": ["/path/to/my-server.js"]
    }
  }
}

Tip: Don't add too many servers — overwhelms agents with options.

Note: Changes persist in agent's global config even without Vibe Kanban.

Remote MCP Support (v0.1.13)

Remote issues/workspaces now support MCP integration. Ensure your remote service is updated to the latest release before relying on MCP tools.

Vibe Kanban MCP Server

Expose Vibe Kanban to external MCP clients (Claude Desktop, Raycast, etc.)

Setup via Web UI

1. Settings → MCP Servers 2. Click Vibe Kanban in "Popular servers" 3. Save Settings

Manual Setup

Add to MCP client config:

{
  "mcpServers": {
    "vibe_kanban": {
      "command": "npx",
      "args": ["-y", "vibe-kanban@latest", "--mcp"]
    }
  }
}

Available Tools

The MCP server is a workspace + issue management surface.

Notes:

• Issues have a simple_id (e.g. PROJ-42) for human-readable reference.
• get_issue returns embedded tags, relationships, and sub-issues.
• Use the list_* tools first to discover IDs.

Tools (grouped):

MCP issue listing now supports richer filtering, which is useful when external MCP clients need to narrow issue sets before calling get_issue or mutation tools.

Example Usage

Create issues from plan:

I need to build user authentication with:
- Registration with email validation
- Login/logout
- Password reset

Then turn this plan into tasks.

MCP client creates structured issues in Vibe Kanban.

Start a workspace session:

Start a workspace session for the current workspace and link it to issue PROJ-42.

Note: MCP server is local-only — cannot be accessed via public URLs.

Self-Hosting Notes (v0.1.13)

Docker Compose URLs and port bindings are configurable for self-hosting. Review your deployment settings after upgrading.

Agent Transport Compatibility (v0.1.15)

• Claude Code integration was updated to handle newer message types.
• If your executor bridge is pinned to older transport assumptions, validate task attempt streaming after upgrade.

Remote Operations (v0.1.32)

• Remote audit logging can be exported through Application Insights OTLP integrations.
• Remote short issue IDs are org-scoped, so cross-org references are less collision-prone.

Troubleshooting

Common issues and solutions.

Agent Reports Empty Codebase

Cause: Git sparse-checkout enabled.

Solution: git sparse-checkout disable

Preview Not Loading

Cause: Dev server URL not detected.

Solution: Ensure dev server prints URL to stdout. Supported formats: http://localhost:3000, https://localhost:3000, http://127.0.0.1:3000

VSCode Extension Empty

Cause: VSCode not opened via Vibe Kanban.

Solution: Click "Open in VSCode" from task view — extension requires worktree context.

Extension Not Loading

Solutions:

• Verify installed: search @id:bloop.vibe-kanban
• Cursor/Windsurf: Install from Open VSX Registry
• Restart IDE

Port Conflicts

Cause: Agents not cleaning up dev servers.

Solutions:

• Use fixed port: PORT=8080 npx vibe-kanban
• Kill stale processes manually

Disable Worktree Cleanup (Debug)

Use case: Preserve all worktrees for debugging or audit.

Set the environment variable to disable all automatic worktree cleanup:

DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban

Re-enable by unsetting the variable once investigation is complete.

Claude Code Session Breaks After Cleanup

Symptom: Claude Code / IDE context breaks after a task/workspace cleanup because the worktree path changed.

Solutions:

• Upgrade Vibe Kanban to version 0.1.23+ (worktree path is preserved across cleanup to maintain session continuity).
• For debugging, temporarily disable cleanup: DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban.

Workspace Logs Missing / Incomplete

Solutions:

• Upgrade Vibe Kanban to version 0.1.23+ (workspace logs capture was updated).
• Upgrade to 0.1.44+ if missing logs happen at the very start of execution; log stores are now pre-registered before normalized streaming begins.
• Enable debug logs to get more detail: RUST_LOG=debug npx vibe-kanban.

Debug Logs

RUST_LOG=debug npx vibe-kanban

Database Reset (Nuclear)

Warning: Deletes ALL tasks and settings.

GitHub CLI Issues

Check: gh --version and gh auth status. Re-auth: gh auth login

Agent Not Executing

Checks:

1. Agent authenticated externally? 2. Correct agent profile selected? 3. Setup scripts failing? 4. View process logs (triple dot → View Processes)

Vibe Guide

Best practices for working with AI coding agents.

Planning

Always Plan First

Ask agent: "come up with a plan, confirm with me before making changes"

Plan More, Review Less

5 min planning saves 10 min reviewing. Plans faster to judge than diffs.

Planning Sets the Shape

Agents optimize for minimal edits. Once code exists, changes patch rather than rethink. Plan picks the right shape before code hardens.

Re-plan When Needed

If making many plan changes: start new session, summarize learnings, let agent begin fresh.

Knowing what you know please write a new high level plan:
- No code
- Just sentences
- Mention files to look at, at the bottom of your plan

Async Work

Use YOLO Mode

Async only works without constant approvals. Use agent's YOLO/dangerously-skip-permissions mode.

Biggest Model is Fastest

Smaller models make more mistakes, need more intervention. With 2+ parallel tasks, big model is faster. Metric: how often you intervene.

Set Up Codebase for QA

Make changes verifiable with dev/test commands. Most changes should end with "tests pass", not "can you try this?"

Solve Dev Servers

Agents bad at starting/cleaning up servers → port conflicts. Use fixed port or Dev Manager MCP.

Add Dummy Data

Make project runnable offline with seed data. Enables parallel agents, avoids database conflicts.

Combating Laziness

No Backwards Compatibility

Add to system prompt:

We want the simplest change possible. We don't care about migration. Code readability matters most.

Disable Disabling Lint Rules

Agents love eslint-disable-next-line. Ban with eslint-comments/no-restricted-disable.

Frontend Tips

Separate Presentation from Logic

Keep leaf components presentational. Business logic in parents. Avoids Frankenstein components.

{
  "no-restricted-syntax": [
    "error",
    {
      "selector": "CallExpression[callee.name=\"useState\"]",
      "message": "View components should not manage state."
    }
  ]
}

Restrict Tailwind

Agents add custom colors/spacing everywhere. Use ESLint to enforce allowed utility classes.

Figma MCP

Good for first pass at presentational components. Specify Tailwind config paths and icon library.

Workspaces (Beta)

New UI mode for multi-repo development, sessions, and improved workflow.

Overview

Workspaces provide a modern interface for working with AI coding agents:

• Multi-repo support: Work across multiple repositories in one workspace
• Sessions: Multiple conversation threads per workspace
• Command Bar: Keyboard-driven navigation (Cmd/Ctrl + K)
• Workspace Notes: Document requirements and decisions
• Integrated Terminal: PTY-backed terminal with xterm.js

Creating Workspaces

1. Click + in sidebar or use Cmd/Ctrl + K → New Workspace 2. Select project from dropdown (or create new) 3. Add repositories:

• Recent repos list
• Browse disk
• Create new repo

4. Set target branches for each repo 5. Describe task in chat input 6. Select agent 7. Click Create

Workspace auto-creates working branch from target branch.

Defaults: Create flow now defaults to the last used project/repo/branch and sets a base target branch automatically. Adjust per repo if needed.

Draft workspace-creation preference is also persisted, which is useful if you regularly stage workspaces before fully launching them.

Workspace Create Flow Updates (v0.1.15)

• Navigation in create flow is standardized via callback handlers.
• Preferred repo/branch selections are preserved more consistently.
• Workspace creation respects executor_config with safer fallback defaults.

Create Workspace from PR

Use the Create Workspace from PR action to prefill repo and branch context from an existing pull request.

Remote Routes

Workspaces support remote routes for deep-linking into a specific workspace context.

Remote Access (v0.1.21)

Remote Access lets you connect to a host machine running Vibe Kanban from another device and access that host's workspaces.

Pair a Host

Host (the machine running Vibe Kanban):

1. Start Vibe Kanban and sign in. 2. Open Settings → Remote Access. 3. Generate / copy the pairing code.

Client (the device you want to control from):

1. Sign in at https://cloud.vibekanban.com 2. Open Remote Access → link/add a host. 3. Paste the pairing code.

After pairing, the client can list and open the host's workspaces.

Security Notes (High Level)

• Pairing is code-based and intended to be explicit (you choose which host to link).
• The model is designed to be “zero trust” style: requests/actions are signed on the client and verified on the host.

Sessions

Conversation threads within a workspace. All sessions share repos and git state.

When to Create New Sessions

• Work on different parts simultaneously
• Try alternative approaches
• Work around token limits
• Use different agents for different tasks

Session States

Creating Sessions

1. Click session dropdown in chat toolbar 2. Select + New Session 3. Provide context about existing work if needed

Sessions maintain independent conversation history.

Session dropdown shows agent icons next to session titles for quick identification.

Session Naming (v0.1.31)

• Sessions can be renamed explicitly.
• Vibe Kanban can also auto-name purpose-specific sessions to keep multi-session workspaces easier to scan.

Command Bar

Central hub for navigation and actions. Press Cmd/Ctrl + K.

Slash Commands

Type / in the chat input to open the slash command menu for quick actions.

Quick Actions

Workspace Actions

Workspace Action Reliability (v0.1.28)

• Spin Off Workspace preserves the working branch more reliably.
• Duplicate Workspace preserves executor configuration instead of falling back unexpectedly.
• Linked issue handling in workspace actions is more reliable, so copied or spun-off workspaces keep better issue continuity.

Workspace Logs Capture (v0.1.23)

Workspace logs capture was updated in v0.1.23 (root execution-process provider). If logs look missing or truncated, upgrading to 0.1.23+ is the first thing to try.

Git Actions

View Toggles

Diff Options

Workspace Notes

Document information in the Notes section of right sidebar:

• Task requirements
• Decisions made
• Which session is for what
• Context for future reference

Interface Guide

Layout Panels

Workspace List

• Shows active workspace count
• Uses infinite scroll pagination for large lists

Sidebar Filters & Sorting (v0.1.7)

• Filter by Project and PR status from the workspace sidebar
• Use No project to show unassigned workspaces
• Sorting in the accordion sidebar prioritizes older completed workspaces
• Needs Attention includes workspaces with unseen activity

Branch Search

Search workspaces by branch name in sidebar.

Drag-and-Drop Images

Drag images directly into chat for context.

As of v0.1.28, image attachments can also be sent during an active agent run, which makes iterative UI and screenshot-driven workflows smoother.

As of v0.1.32, attachments are no longer limited to images; arbitrary attachments can be carried across workspace and issue flows.

Integrated Terminal

PTY-backed terminal with full shell support:

• Expandable in logs panel
• Shell init scripts supported
• WebSocket reconnection for stability

Multi-Repo Workspaces

Work across multiple repositories:

• Each repo has independent git state
• Per-repo commands in Command Bar
• Commits behind indicator in git panel

Per-Repo Actions

Duplicating Workspaces

Use Cmd/Ctrl + K → Workspace Actions → Duplicate Workspace

Duplicates repos and branch config with fresh conversation.

Spin Off Workspace

Use Spin Off Workspace to create a child workspace from the current one.

In v0.1.15, spin-off preserves linked issue context and preferred repository/branch metadata more reliably.

In v0.1.28, spin-off also preserves the branch more reliably during workspace actions.

Archiving

Archive completed workspaces:

• Navbar: Click Archive button
• Command Bar: Workspace Actions → Archive

View archive at bottom of sidebar. Use Pin for important active workspaces.

Simple IDs

Issues have readable IDs like BLO-5 for easy reference.