https://github.com/rookedsysc/kanvibe
Self-hosted Kanban board with browser terminals for AI coding agents. Hook-driven auto-tracking — manage tmux/zellij sessions and git worktrees from one board.
https://github.com/rookedsysc/kanvibe
ai-agent claude-code developer-tools git-worktree kanban self-hosted task-management terminal terminal-multiplexer tmux typescript vibe-coding vibecoding zellij
Last synced: about 1 month ago
JSON representation
Self-hosted Kanban board with browser terminals for AI coding agents. Hook-driven auto-tracking — manage tmux/zellij sessions and git worktrees from one board.
- Host: GitHub
- URL: https://github.com/rookedsysc/kanvibe
- Owner: rookedsysc
- License: agpl-3.0
- Created: 2026-02-10T11:39:12.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-01T14:04:28.000Z (about 1 month ago)
- Last Synced: 2026-04-04T07:59:21.307Z (about 1 month ago)
- Topics: ai-agent, claude-code, developer-tools, git-worktree, kanban, self-hosted, task-management, terminal, terminal-multiplexer, tmux, typescript, vibe-coding, vibecoding, zellij
- Language: TypeScript
- Homepage:
- Size: 6.38 MB
- Stars: 102
- Watchers: 0
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](#ai-agent-hooks---automatic-status-tracking) — no manual updates needed.
[](https://buymeacoffee.com/rookedsysc)
> Buying me a coffee is nice, but honestly? A contribution would make my day even more. :)
[KO](./docs/README.ko.md) | [ZH](./docs/README.zh.md)
[](https://www.youtube.com/watch?v=8JTrvd3T_Z0)
**▶ [Watch Demo on YouTube](https://www.youtube.com/watch?v=8JTrvd3T_Z0)**
---
## Prerequisites
The `kanvibe` CLI script automatically checks and installs missing dependencies. You can also install them manually:
| Dependency | Version | Required | Install |
|------------|---------|----------|---------|
| [Node.js](https://nodejs.org/) | >= 22 | Yes | `brew install node` |
| [pnpm](https://pnpm.io/) | latest | Yes | `corepack enable && corepack prepare pnpm@latest --activate` |
| [Docker](https://www.docker.com/) | latest | Yes | `brew install --cask docker` |
| [git](https://git-scm.com/) | latest | Yes | `brew install git` |
| [tmux](https://github.com/tmux/tmux) | latest | Yes | `brew install tmux` |
| [gh](https://cli.github.com/) | latest | Yes | `brew install gh` (requires `gh auth login`) |
| [zellij](https://github.com/zellij-org/zellij) | latest | No | `brew install zellij` |
> Docker is used to run the PostgreSQL database via Docker Compose.
---
## Quick Start
### 1. Configure Environment
```bash
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
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
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](#ai-agent-hooks---automatic-status-tracking) 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](https://github.com/openai/codex/discussions/2150) — 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](https://opencode.ai/docs/plugins/) 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](./LICENSE) for details.
---
## Contributing
See [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) for guidelines.
---
## Inspired By
- [workmux](https://github.com/raine/workmux) — tmux workspace manager
- [vibe-kanban](https://github.com/BloopAI/vibe-kanban) — AI-powered Kanban board