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
i18n	next-intl
Container	Docker Compose

License

This project is licensed under the AGPL-3.0. You are free to use, modify, and extend it for open-source purposes. Commercial SaaS distribution is not permitted under this license. See LICENSE for details.

Contributing

See docs/CONTRIBUTING.md for guidelines.

Inspired By

workmux — tmux workspace manager
vibe-kanban — AI-powered Kanban board

NAME

SYNOPSIS

INFO

DESCRIPTION

README