Tools
Claw Kanban
By AI Agent Orchestration Kanban Board โ Route tasks to Claude Code, Codex CLI, and Gemini CLI with role-based auto-assignment and real-time monitoring
Install
npm install -gREADME
<p align="center">
<img src="public/kanban-claw.svg" width="80" alt="Claw Kanban" />
</p>
<h1 align="center">Claw-Kanban</h1>
<p align="center">
<strong>AI Agent Orchestration Kanban Board</strong><br>
Route tasks to <b>Claude Code</b>, <b>Codex CLI</b>, and <b>Gemini CLI</b> with role-based auto-assignment and real-time monitoring.
</p>
<p align="center">
<img src="https://img.shields.io/badge/version-1.0.1-blue" alt="Version" />
<img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen" alt="Node.js 22+" />
<img src="https://img.shields.io/badge/license-Apache%202.0-orange" alt="License" />
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey" alt="Platform" />
<img src="https://img.shields.io/badge/AI-Claude%20%7C%20Codex%20%7C%20Gemini-purple" alt="AI Agents" />
</p>
<p align="center">
<a href="#install-with-ai">Install with AI</a> ·
<a href="#features">Features</a> ·
<a href="#architecture">Architecture</a> ·
<a href="#api-reference">API</a> ·
<a href="#changelog">Changelog</a> ·
<a href="README.ko.md">ํ๊ตญ์ด</a>
</p>
---
## Install with AI
> **Just paste this to your AI coding agent (Claude Code, Codex, Gemini CLI, Cursor, etc.):**
>
> ```
> Install Claw-Kanban following the guide at:
> https://github.com/GreenSheep01201/Claw-Kanban
> ```
>
> The AI will read this README and handle everything automatically.
---
## AI Installation Guide
> **This section is written for AI coding agents.**
> If you are an AI assistant and the user has asked you to install Claw-Kanban, follow the steps below exactly. Each step includes a verification command โ run it and confirm success before proceeding to the next step.
### Step 0: Check Prerequisites
```bash
# 1. Check Node.js version (must be 22 or higher)
node -v
# Expected: v22.x.x or higher. If missing or below v22, stop and tell the user:
# "Node.js 22+ is required. Install from https://nodejs.org/ or use nvm: nvm install 22"
# 2. Check for pnpm (recommended) or npm
pnpm -v || npm -v
# If pnpm is missing, install it:
# npm install -g pnpm
# 3. Check for at least one AI CLI tool
which claude || which codex || which gemini
# If none found, tell the user to install at least one:
# Claude Code: npm i -g @anthropic-ai/claude-code && claude login
# Codex CLI: npm i -g @openai/codex && codex auth login
# Gemini CLI: npm i -g @google/gemini-cli && gemini auth login
```
### Step 1: Clone and Build
```bash
git clone https://github.com/GreenSheep01201/Claw-Kanban.git
cd Claw-Kanban
pnpm install # or: npm install
pnpm build # or: npm run build
```
**Verify:** `ls dist/index.html` should exist.
### Step 2: Start the Server
```bash
pnpm start
# Server starts at http://127.0.0.1:8787
```
**Verify:** `curl -s http://127.0.0.1:8787/api/health` should return `{"ok":true, ...}`.
### Step 3: Open the Dashboard
Tell the user:
```
Claw-Kanban is installed and running!
Dashboard: http://127.0.0.1:8787
```
### Optional: AGENTS.md Setup
If the user wants AI agents to auto-register kanban tasks from chat messages:
```bash
pnpm setup
# This prepends orchestration rules to the workspace AGENTS.md
```
### Optional: Development Mode
For development with hot reload:
```bash
pnpm dev # LAN accessible (0.0.0.0)
pnpm dev:local # localhost only (127.0.0.1)
# UI: http://127.0.0.1:5173 | API: http://127.0.0.1:8787
```
### Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| `pnpm build` fails with "node:sqlite" error | Node.js < 22 | Upgrade to Node.js 22+: `nvm install 22 && nvm use 22` |
| Port 8787 already in use | Another process on port | `lsof -i :8787` to find it, or set `PORT=9999 pnpm start` |
| `curl /api/health` connection refused | Server not running | Run `pnpm start` from the Claw-Kanban directory |
| No AI providers shown in Settings | CLI tools not installed | Install at least one: `npm i -g @anthropic-ai/claude-code` |
| Provider shows "Not Authenticated" | CLI tool not logged in | Run the auth command: `claude login`, `codex auth login`, or `gemini auth login` |
---
## Why?
Using multiple AI coding agents (Claude Code, Codex CLI, Gemini CLI) means juggling multiple terminal windows, manually deciding which agent to use for each task, and waiting blindly until they finish. Claw-Kanban solves this by providing a single dashboard where you can:
- **Auto-assign agents by role** โ no more manual switching between terminals
- **Watch agents work in real-time** โ no more blind waiting; see exactly what your agent is doing
- **Dispatch tasks from your phone** โ send `# fix the login bug` via Telegram and the agent handles the rest
## Features
- **6-Column Kanban Board** โ Inbox, Planned, In Progress, Review/Test, Done, Stopped
- **Multi-Agent Orchestration** โ Spawn and manage Claude Code, Codex CLI, and Gemini CLI processes
- **Role-Based Auto-Assignment** โ Automatically route tasks by role (DevOps / Backend / Frontend) and task type (New / Modify / Bugfix)
- **AI Provider Detection** โ Settings panel shows install and auth status for each CLI tool; unauthenticated providers are disabled in dropdowns
- **Automatic Review** โ After implementation completes, auto-trigger a review/test cycle via Claude
- **Real-time Terminal Viewer** โ Live agent output in the browser; no more waiting blindly for completion
- **Chat-to-Card** โ Send `# task description` via Telegram, Slack, or any webhook source to instantly create a kanban card
- **OpenClaw Gateway Integration** โ Optional wake notifications on card status changes
- **Project Path Safety** โ Dedicated `project_path` field per card; server blocks agent runs when path is unset to prevent working in the wrong directory
- **Multi-Language Orchestration** โ AGENTS.md rules auto-detect user language (Korean, English, etc.) and respond accordingly
- **Modern Dark UI** โ React 19, responsive, glassmorphism design
- **SQLite Storage** โ Zero-config, file-based database via Node.js built-in `node:sqlite`
- **Cross-Platform** โ macOS, Linux, and Windows (PowerShell)
## Screenshots
### Kanban Dashboard
<p align="center">
<img src="sample_img/dashboard.png" width="800" alt="Claw-Kanban Dashboard" />
</p>
> 6-column kanban board with card detail panel. Create tasks, assign AI agents, and monitor progress in real-time.
### Provider Settings
<p align="center">
<img src="sample_img/provider_setting.png" width="600" alt="Provider Settings" />
</p>
> Auto-detect installed AI CLI tools (Claude Code, Codex CLI, Gemini CLI) and configure role-based provider mapping.
### Real-time Terminal Viewer
<p align="center">
<img src="sample_img/claude_code_tm.png" width="800" alt="Terminal Viewer" />
</p>
> See exactly what your AI agent is doing in real-time. No more waiting blindly for completion โ open the terminal viewer and watch the agent work.
### Telegram Integration
<p align="center">
<img src="sample_img/telegram.png" width="400" alt="Telegram Integration" />
</p>
> Send `# fix the login bug` from Telegram and a kanban card is created automatically. The agent runs, completes the work, and reports back โ dispatch tasks from your phone on the go.
## Prerequisites
- **Node.js 22+** (required for `node:sqlite`)
- **pnpm** (recommended) or npm
- At least one AI CLI tool installed and authenticated:
| Tool | Install | Authenticate |
|------|---------|-------------|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `npm i -g @anthropic-ai/claude-code` | `claude login` |
| [OpenAI Codex CLI](https://github.com/openai/codex) | `npm i -g @openai/codex` | `codex auth login` |
| [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm i -g @google/gemini-cli` | `gemini auth login` |
## Quick Start
### One-Line Install
**macOS / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/GreenSheep01201/Claw-Kanban/main/install.sh | bash
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/GreenSheep01201/Claw-Kanban/main/install.ps1 | iex
```
The installer clones the repo, installs dependencies, builds the UI, configures `.env` and `AGENTS.md`, and registers an auto-start service (launchd on macOS, systemd on Linux).
### Manual Install
```bash
git clone https://github.com/GreenSheep01201/Claw-Kanban.git
cd Claw-Kanban
pnpm install
pnpm build
```
### Running
```bash
# Production (serves built UI)
pnpm start
# Development (Vite HMR + API with hot reload, LAN accessible)
pnpm dev
# Development (localhost only)
pnpm dev:local
```
| | URL |
|---|---|
| **UI** | http://127.0.0.1:5173 (dev) or http://127.0.0.1:8787 (prod) |
| **API** | http://127.0.0.1:8787 |
## How It Works
```
1. Task arrives (UI / API / webhook) โโ> Card created in Inbox
2. Click "Start" or auto-assign โโ> CLI process spawned (Claude/Codex/Gemini)
3. Card moves to "In Progress" โโ> Real-time terminal logs available
4. Agent completes (exit 0) โโ> Card auto-moves to "Review/Test"
5. Auto-review triggers โโ> Claude reviews the work
6. Review passes โโ> Card moves to "Done" + wake notification
7. Review fails โโ> Stays in "Review/Test", issues reported
```
### Project Path
The agent needs to know **which project directory** to work in. There are three ways to set it:
**1. Dedicated `project_path` field (recommended):**
Set it in the UI card detail panel, or via API:
```bash
# When creating a card
curl -X POST http://127.0.0.1:8787/api/cards \
-H 'content-type: application/json' \
-d '{"title":"fix bug","description":"...","project_path":"/Users/me/projects/my-app"}'
# When updating an existing card
curl -X PATCH http://127.0.0.1:8787/api/cards/<id> \
-H 'content-type: application/json' \
-d '{"project_path":"/Users/me/projects/my-app"}'
```
**2. Description section (legacy, still supported):**
```
Fix the login button style
#
... (truncated)
tools
Comments
Sign in to leave a comment