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. :)
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.
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!) |
bash kanvibe.sh startThis command checks dependencies (with i18n install prompts), installs packages, starts PostgreSQL, runs migrations, builds, and launches the server.
bash kanvibe.sh stopStops the KanVibe server and PostgreSQL container.
Open http://localhost:4885 in your browser.
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.
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
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.
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.
- 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
- 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
- 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
KanVibe integrates with Claude Code Hooks, Gemini CLI Hooks, and Codex CLI 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 |
User sends prompt → PROGRESS
AI asks question (AskUser) → PENDING
User answers → PROGRESS
AI finishes response → REVIEW
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.
agent-turn-complete (agent done) → REVIEW
Codex CLI currently only supports the
agent-turn-completenotification event via thenotifyconfig. PROGRESS and PENDING transitions are not yet available. OpenAI is actively designing a hooks system — full support will be added when it ships.
Claude Code and Gemini CLI hooks are auto-installed when you register a project through KanVibe's directory scan. You can also install them individually from the project settings or task detail page. Codex CLI requires manual configuration.
| 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 |
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.
| Endpoint | Method | Description |
|---|---|---|
/api/hooks/start |
POST | Create a new task |
/api/hooks/status |
POST | Update task status by branchName + projectName |
- 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
- Supported languages: Korean (ko), English (en), Chinese (zh)
- Powered by next-intl
| 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 |
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.
See docs/CONTRIBUTING.md for guidelines.
- workmux — tmux workspace manager
- vibe-kanban — AI-powered Kanban board