KanVibe

AI Agent Task Management Kanban Board

A web-based terminal Kanban board for managing AI coding agent (Claude Code, Gemini CLI, Codex CLI, etc.) tasks in real-time. Monitor tmux/zellij sessions directly in your browser while tracking task progress on a drag & drop Kanban board. Automatically track task status via AI Agent Hooks — no manual updates needed.

Buying me a coffee is nice, but honestly? A contribution would make my day even more. :)

KO | ZH

▶ Watch Demo on YouTube

Prerequisites

The kanvibe CLI script automatically checks and installs missing dependencies. You can also install them manually:

| Dependency | Version | Required | Install | |------------|---------|----------|---------| | Node.js | >= 22 | Yes | brew install node | | pnpm | latest | Yes | corepack enable && corepack prepare pnpm@latest --activate | | Docker | latest | Yes | brew install --cask docker | | git | latest | Yes | brew install git | | tmux | latest | Yes | brew install tmux | | gh | latest | Yes | brew install gh (requires gh auth login) | | zellij | latest | No | brew install zellij |

Docker is used to run the PostgreSQL database via Docker Compose.

Quick Start

1. Configure Environment

cp .env.example .env

| Variable | Description | Default | |----------|-------------|---------| | PORT | Web server port | 4885 | | DB_PORT | PostgreSQL port | 4886 | | KANVIBE_USER | Login username | admin | | KANVIBE_PASSWORD | Login password | changeme (change this!) |

2. Run

bash kanvibe.sh start          # Interactive mode selection (foreground/background)
bash kanvibe.sh start --fg     # Foreground (output to terminal, Ctrl+C to stop)
bash kanvibe.sh start --bg     # Background (server keeps running after terminal closes)

This command checks dependencies (with i18n install prompts), installs packages, starts PostgreSQL, runs migrations, builds, and launches the server.

bash kanvibe.sh stop

Stops the KanVibe server and PostgreSQL container.

Open http://localhost:4885 in your browser.

Usage Flow

1. Register a Project

Search for your local git repository using the fzf-style folder search in project settings. KanVibe scans the directory and automatically detects existing worktree branches.

2. Create Tasks

Add a TODO task from the Kanban board. When creating a task with a branch name, KanVibe automatically:

• Creates a git worktree for the branch
• Spawns a tmux window or zellij tab for the session
• Links the terminal session to the task

3. Work with the Kanban Board

Tasks are managed through 5 statuses: TODO → PROGRESS → PENDING → REVIEW → DONE

Change statuses via drag & drop, or let AI Agent Hooks transition them automatically. When a task moves to DONE, its branch, worktree, and terminal session are automatically deleted.

4. Select Pane Layouts

Each task's terminal page supports multiple pane layouts:

| Layout | Description | |--------|-------------| | Single | One full-screen pane | | Horizontal 2 | Two panes side by side | | Vertical 2 | Two panes stacked | | Left + Right TB | Left pane + right top/bottom split | | Left TB + Right | Left top/bottom split + right pane | | Quad | Four equal panes |

Each pane can run a custom command (e.g., vim, htop, lazygit, test runner, etc.). Configure layouts globally or per-project from the settings dialog.

Features

Kanban Board

• 5-status task management (TODO / PROGRESS / PENDING / REVIEW / DONE)
• Custom task ordering with drag & drop
• Multi-project filtering
• Done column pagination
• Real-time WebSocket updates

Git Worktree Integration

• Automatic git worktree creation when a branch-based task is created
• Worktree scanning: existing branches are auto-registered as TODO tasks
• Automatic cleanup (branch + worktree + session) when task moves to DONE

Terminal Sessions (tmux / zellij)

• tmux and zellij are both supported as terminal multiplexers
• Browser-based terminal via xterm.js + WebSocket
• SSH remote terminal support (reads ~/.ssh/config)
• Nerd Font rendering support

AI Agent Hooks - Automatic Status Tracking

KanVibe integrates with Claude Code Hooks, Gemini CLI Hooks, Codex CLI, and OpenCode to automatically track task status. Tasks are managed through 5 statuses:

| Status | Description | |--------|-------------| | TODO | Initial state when a task is created | | PROGRESS | AI is actively working on the task | | PENDING | AI asked a follow-up question; waiting for user response (Claude Code only) | | REVIEW | AI has finished; awaiting review | | DONE | Task complete — branch, worktree, and terminal session are automatically deleted |

Claude Code

User sends prompt          → PROGRESS
AI asks question (AskUser) → PENDING
User answers               → PROGRESS
AI finishes response       → REVIEW

Gemini CLI

BeforeAgent (user prompt)  → PROGRESS
AfterAgent (agent done)    → REVIEW

Gemini CLI does not have an equivalent to Claude Code's AskUserQuestion, so the PENDING state is not available.

Codex CLI (Partial Support)

agent-turn-complete (agent done) → REVIEW

Codex CLI currently only supports the agent-turn-complete notification event via the notify config. PROGRESS and PENDING transitions are not yet available. OpenAI is actively designing a hooks system — full support will be added when it ships.

OpenCode

User sends message (message.updated, role=user) → PROGRESS
AI asks a question (question.asked)             → PENDING
User answers question (question.replied)        → PROGRESS
Session idle (session.idle)                     → REVIEW

OpenCode uses its own plugin system instead of shell-script hooks. KanVibe generates a TypeScript plugin at .opencode/plugins/kanvibe-plugin.ts that subscribes to OpenCode's native event hooks (message.updated, question.asked, question.replied, and session.idle) via the @opencode-ai/plugin SDK. This means status updates are handled in-process without spawning external shell commands.

All agent hooks are auto-installed when you register a project through KanVibe's directory scan or create a task with a worktree. You can also install them individually from the task detail page.

| Agent | Hook Directory | Config File | |-------|---------------|-------------| | Claude Code | .claude/hooks/ | .claude/settings.json | | Gemini CLI | .gemini/hooks/ | .gemini/settings.json | | Codex CLI | .codex/hooks/ | .codex/config.toml | | OpenCode | .opencode/plugins/ | Plugin auto-discovery |

Browser Notifications

Task status changes via AI Agent Hooks trigger browser notifications with project, branch, and status. Click to jump directly to the task detail page.

• Real-time alerts — Instant notifications for task status changes
• Background mode — Notifications work even when KanVibe is not focused
• Smart navigation — Click notification → task detail page (with correct language)
• Configurable — Enable/disable per project and filter by status (PROGRESS, PENDING, REVIEW, DONE)

Setup: Browser will prompt for permission on first visit. Configure filters in Project Settings → Notifications.

Hook API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /api/hooks/start | POST | Create a new task | | /api/hooks/status | POST | Update task status by branchName + projectName |

GitHub-style Diff View

Review code changes directly in the browser with a GitHub-style diff viewer. Click the Diff badge on the task detail page to see all modified files compared to the base branch.

• File tree sidebar with changed file count
• Inline diff viewer powered by Monaco Editor
• Edit mode for quick fixes directly in the browser
• Viewed file tracking with checkboxes

Pane Layout Editor

• 6 layout presets (Single, Horizontal 2, Vertical 2, Left+Right TB, Left TB+Right, Quad)
• Per-pane custom command configuration
• Global and per-project layout settings

Internationalization (i18n)

• Supported languages: Korean (ko), English (en), Chinese (zh)
• Powered by next-intl

Tech Stack

| Category | Technology | |----------|------------| | Frontend/Backend | Next.js 16 (App Router) + React 19 + TypeScript | | Database | PostgreSQL 16 + TypeORM | | Styling | Tailwind CSS v4 | | Terminal | xterm.js + WebSocket + node-pty | | SSH | ssh2 (Node.js) | | Drag & Drop | @hello-pangea/dnd | | i1