Claw-Kanban

AI Agent Orchestration Kanban Board
Route tasks to Claude Code, Codex CLI, Gemini CLI, OpenCode, GitHub Copilot, and Google Antigravity with role-based auto-assignment and real-time monitoring.

Install with AI · Features · Architecture · API · Changelog · 한국어

---

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

# 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

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

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

Step 3.5: AGENTS.md Setup (Required)

This step is required for AI agent orchestration. It teaches your AI coding agent how to interact with the kanban board — without it, the agent cannot register tasks, route work, or manage cards.

pnpm setup
# This prepends orchestration rules to the workspace AGENTS.md

Verify: Your workspace AGENTS.md should now contain <!-- BEGIN claw-kanban orchestration rules --> at the top.

Optional: Development Mode

For development with hot reload:

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, OpenCode, Copilot, Antigravity) 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
• Use your existing CLI environment — CLI agents inherit your skills, MCP servers, custom instructions, and all settings with zero additional configuration

Dual Execution Model

Claw-Kanban supports 6 AI agents through two execution modes:

CLI Agents — Your Environment, Your Rules

Agent	Execution	Setup
Claude Code	CLI spawn	npm i -g @anthropic-ai/claude-code && claude login
Codex CLI	CLI spawn	npm i -g @openai/codex && codex auth login
Gemini CLI	CLI spawn	npm i -g @google/gemini-cli && gemini auth login
OpenCode	CLI spawn	npm i -g opencode && opencode auth

CLI agents spawn the actual CLI binary installed on your machine. This means your entire personalized environment carries over automatically:

• Custom skills and agents you've configured
• MCP server connections
• Project-specific instructions (CLAUDE.md, etc.)
• Authentication and API keys
• All CLI settings and preferences

No additional setup needed — if claude, codex, or gemini works in your terminal, it works in Claw-Kanban. This is the key advantage of CLI agents: they use your existing workflow as-is.

HTTP Agents — Zero Install, OAuth Only

Agent	Execution	Setup
GitHub Copilot	Direct API call	OAuth Connect in Settings
Google Antigravity	Direct API call	OAuth Connect in Settings

HTTP agents call provider APIs directly from the server. No CLI installation required — just connect your GitHub or Google account via OAuth in the Settings panel. Tokens are encrypted at rest (AES-256-GCM).

Features

• 6-Column Kanban Board — Inbox, Planned, In Progress, Review/Test, Done, Stopped
• Multi-Agent Orchestration — Manage 6 AI agents: Claude Code, Codex CLI, Gemini CLI, OpenCode, GitHub Copilot, Google Antigravity
• Dual Execution Model — CLI agents (spawn local processes, inherit your environment) + HTTP agents (direct API calls, OAuth only)
• 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
• OAuth Connect (optional) — For environments where CLI auth isn't possible, or to use Copilot/Antigravity; connect via browser and store credentials server-side (encrypted)
• 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

6-column kanban board with card detail panel. Create tasks, assign AI agents, and monitor progress in real-time.

Provider Settings

Auto-detect installed AI CLI tools (Claude Code, Codex CLI, Gemini CLI) and configure role-based provider mapping.

Real-time Terminal Viewer

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

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 agent available:

CLI Agents — Install and authenticate the CLI tool. Your existing configuration (skills, agents, MCP servers, custom instructions) carries over automatically.

Tool	Install	Authenticate
Claude Code	npm i -g @anthropic-ai/claude-code	claude login
OpenAI Codex CLI	npm i -g @openai/codex	codex auth login
Google Gemini CLI	npm i -g @google/gemini-cli	gemini auth login
OpenCode	npm i -g opencode	opencode auth

HTTP Agents — No CLI needed. Connect via OAuth in the Settings panel after starting the server.

Tool	Setup
GitHub Copilot	Settings > OAuth Connect > GitHub
Google Antigravity	Settings > OAuth Connect > Google

Quick Start

One-Line Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/GreenSheep01201/Claw-Kanban/main/install.sh | bash

Windows (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

git clone https://github.com/GreenSheep01201/Claw-Kanban.git
cd Claw-Kanban
pnpm install
pnpm build

Running

# 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      ──>  Agent launched:
   • CLI agents (Claude/Codex/Gemini) ──>  CLI process spawned (inherits your environment)
   • HTTP agents (Copilot/Antigravity)──>  Direct API call (OAuth tokens)
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:

# 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

## Project Path
/Users/me/projects/my-app

3. Webhook with project_path:

curl -X POST http://127.0.0.1:8787/api/inbox \
  -H 'content-type: application/json' \
  -d '{"text":"fix the build","source":"telegram","project_path":"/Users/me/projects/my-app"}'

Fallback chain: card.project_path field > description ## Project Path section > blocked (server returns error)

Note: The server blocks /run and /review if no project path can be resolved. This prevents agents from running in the wrong directory.

Task Flow Diagram

               ┌─────────┐
  UI / API ──> │  Inbox   │
  Webhook  ──> │         │
               └────┬────┘
                    │ Start (manual or auto)
               ┌────▼────┐
               │ Planned  │  (optional staging)
               └────┬────┘
                    │
               ┌────▼─────────┐
               │ In Progress   │  <── CLI agent running
               │ (terminal log)│
               └────┬─────────┘
                    │ exit 0
               ┌────▼─────────┐
               │ Review/Test   │  <── Claude auto-review
               └──┬────────┬──┘
          pass    │        │  issues found
          ┌───────▼┐   ┌───▼────┐
          │  Done   │   │Stopped │
          └────────┘   └────────┘

Configuration

Environment Variables

Copy .env.example to .env:

cp .env.example .env

Variable	Default	Description
PORT	8787	API server port
HOST	127.0.0.1	Bind address (0.0.0.0 for LAN/Tailscale)
DB_PATH	./kanban.sqlite	SQLite database file path
LOGS_DIR	./logs	Agent terminal log directory
OPENCLAW_CONFIG	(empty)	Path to openclaw.json for gateway wake integration
OAUTH_ENCRYPTION_SECRET	(empty)	Required for OAuth Connect. Secret used to encrypt OAuth tokens at rest (AES-256-GCM). Can reuse SESSION_SECRET.
OAUTH_BASE_URL	http://HOST:PORT	Public base URL used to build OAuth redirect URIs (set if HOST/PORT differ from browser access)
ANTIGRAVITY_GITHUB_CLIENT_ID	(empty)	GitHub OAuth App client id for antigravity provider
ANTIGRAVITY_GITHUB_CLIENT_SECRET	(empty)	GitHub OAuth App client secret for antigravity provider
ANTIGRAVITY_GITHUB_SCOPE	read:user user:email	GitHub OAuth scopes requested by antigravity provider

OAuth Connect (optional)

If a machine cannot authenticate CLI tools (e.g. locked-down environments), you can use OAuth Connect from the Settings modal.

Copilot decision (v1): this repo uses GitHub OAuth web login (Authorization Code + PKCE) rather than asking for a GitHub PAT. This is the lowest-friction approach to avoid users creating long-lived PATs.

• Scopes requested are controlled via ANTIGRAVITY_GITHUB_SCOPE (default: read:user user:email).
• Tokens are stored server-side in SQLite and encrypted at rest using OAUTH_ENCRYPTION_SECRET.

Provider Settings (UI)

Open Settings in the UI to configure:

Section	Description
AI Providers	Shows install/auth status for Claude, Codex, Gemini. Re-check button refreshes detection.
Auto-assign	Toggle role-based provider auto-assignment on/off
Role-based Providers	Map DevOps / Backend roles to a default provider
FrontEnd Providers	Map New / Modify / Bugfix task types to providers
Stage-based Providers	Optional overrides for In Progress and Review/Test stages

Default mapping:

Role	Task Type	Default Provider
DevOps	—	Claude Code
Backend	—	Codex CLI
Frontend	New	Gemini CLI
Frontend	Modify	Claude Code
Frontend	Bugfix	Claude Code

AGENTS.md Integration

The setup script prepends kanban orchestration rules to your workspace AGENTS.md:

pnpm setup                                     # auto-detect location
pnpm setup -- --agents-path /path/to/AGENTS.md  # custom path

This teaches your AI agent to recognize #-prefixed messages as task requests and register them on the board.

OpenClaw Gateway

Set OPENCLAW_CONFIG in .env to enable wake notifications:

OPENCLAW_CONFIG=~/.openclaw/openclaw.json

Wake notifications fire on:

• New Inbox card creation
• Card moving from Review/Test to Done

Architecture

Claw-Kanban/
├── server/
│   └── index.ts            # Express 5 API server
│                            #   - SQLite storage (node:sqlite)
│                            #   - Agent process spawn/kill
│                            #   - CLI detection (GET /api/cli-status)
│                            #   - Gateway wake integration
├── src/
│   ├── App.tsx              # Kanban board + Settings modal
│   ├── App.css              # Dark theme (CSS variables)
│   ├── api.ts               # Frontend API client + TypeScript types
│   ├── main.tsx             # React 19 entry point
│   └── index.css            # Base/reset styles
├── public/
│   └── kanban-claw.svg      # App icon (OpenClaw lobster + kanban box)
├── templates/
│   └── AGENTS-kanban.md     # AGENTS.md orchestration rules template
├── scripts/
│   ├── setup.mjs            # AGENTS.md setup (prepend, not overwrite)
│   └── kanban.mjs           # Process management (start/stop/status)
├── install.sh               # One-line installer (macOS/Linux)
├── install.ps1              # One-line installer (Windows)
├── .env.example             # Environment variable template
├── vite.config.ts           # Vite config (dev proxy to API)
└── package.json

Tech Stack

Layer	Technology
Frontend	React 19 + TypeScript + Vite
Backend	Express 5 + Node.js 22+
Database	SQLite (via node:sqlite, zero dependencies)
CLI Agents	Claude Code, Codex CLI, Gemini CLI, OpenCode (local process spawn)
HTTP Agents	GitHub Copilot, Google Antigravity (direct API + OAuth)
Process Mgmt	Node child_process (CLI) + fetch streaming (HTTP)

API Reference

Cards

Method	Endpoint	Description
GET	/api/cards	List all cards (optional ?status=Inbox)
GET	/api/cards/search?q=keyword	Search cards across all fields
POST	/api/cards	Create a card
PATCH	/api/cards/:id	Update card fields
DELETE	/api/cards/:id	Delete card and all artifacts
POST	/api/cards/purge?status=Done	Bulk delete by status

Agent Control

Method	Endpoint	Description
POST	/api/cards/:id/run	Start agent (spawns CLI process)
POST	/api/cards/:id/stop	Stop running agent (kill process tree)
POST	/api/cards/:id/review	Manually trigger review
GET	/api/cards/:id/terminal	Stream terminal output (?lines=200&pretty=1)
GET	/api/cards/:id/logs	Get card event logs

Settings & Status

Method	Endpoint	Description
GET	/api/settings	Get provider settings
PUT	/api/settings	Save provider settings
GET	/api/cli-status	Detect CLI install/auth status (30s cache, ?refresh=1 to bypass)
GET	/api/oauth/antigravity/start	Start OAuth (redirects to GitHub)
GET	/api/oauth/antigravity/callback	OAuth callback (stores token server-side)
GET	/api/oauth/status	OAuth connection status
POST	/api/oauth/disconnect	Disconnect OAuth (body: { provider?: string })

Webhook

POST /api/inbox
Content-Type: application/json

{ "text": "# Fix the login bug", "source": "telegram", "author": "user123", "project_path": "/path/to/project" }

project_path is optional in webhook payloads. If omitted, the orchestrator will ask the user before running the agent.

Health

GET /api/health    # { ok, version, dbPath, gateway }

CLI Detection

The /api/cli-status endpoint checks each tool:

Check	Method
Installed	which (Unix) / where (Windows) + --version
Claude auth	~/.claude.json contains oauthAccount key
Codex auth	~/.codex/auth.json contains OPENAI_API_KEY or tokens; fallback to OPENAI_API_KEY env var
Gemini auth	~/.gemini/oauth_creds.json contains access_token; on Windows also checks %APPDATA%\gcloud\application_default_credentials.json

Results are cached for 30 seconds. Use ?refresh=1 to force re-check.

Security

Claw-Kanban is a local development tool. Important notes:

• No Authentication — Bind to 127.0.0.1 (default). Only use 0.0.0.0 on trusted networks (VPN/Tailscale).
• Agent Permission Flags — --dangerously-skip-permissions (Claude), --yolo (Codex/Gemini) are used for autonomous operation.
• Environment Inheritance — Child processes inherit the server's environment.
• CORS — Open CORS enabled for Vite dev proxy. Do not expose to the public internet.
• OAuth token storage — OAuth tokens are stored server-side only in SQLite and encrypted at rest using OAUTH_ENCRYPTION_SECRET (AES-256-GCM). The browser never receives refresh tokens.
• Built-in OAuth Client IDs — The GitHub and Google OAuth client IDs/secrets embedded in the source code are public OAuth app credentials, not user secrets. Per Google's documentation, client secrets for installed/desktop apps are "not treated as a secret." This is standard practice for open-source apps (VS Code, Thunderbird, GitHub CLI, etc.). These credentials only identify the app itself — your personal tokens are always encrypted separately.
• No personal credentials in source — All user-specific tokens (GitHub, Google OAuth) are stored encrypted in the local SQLite database, never in source code. The encryption key is derived from your OAUTH_ENCRYPTION_SECRET environment variable.
• Copilot token caching — Exchanged Copilot session tokens are cached in-memory only (never written to disk) and auto-expire. Cache is invalidated on re-authentication.

Platform Support

Platform	Status	Notes
macOS	Fully tested	Primary dev platform. 100% working. launchd auto-start.
Linux	Fully supported	systemd user service auto-start.
Windows	Supported	PowerShell installer available. Process management uses taskkill for reliable cleanup.

Management

# Using the management script
node scripts/kanban.mjs status    # Check if server is running
node scripts/kanban.mjs start     # Start in background
node scripts/kanban.mjs stop      # Stop server
node scripts/kanban.mjs restart   # Restart server

# macOS (launchd)
launchctl kickstart -k gui/$(id -u)/ai.openclaw.kanban   # restart
launchctl bootout gui/$(id -u)/ai.openclaw.kanban         # stop

# Linux (systemd)
systemctl --user restart claw-kanban
systemctl --user stop claw-kanban
systemctl --user status claw-kanban

Changelog

v1.0.3

• POST /api/wake endpoint — Agents can now send wake notifications via HTTP (curl) instead of requiring the external openclaw CLI
• AGENTS.md template updated — All openclaw gateway wake references replaced with curl commands to the new /api/wake endpoint

v1.0.2

• GitHub Copilot direct API — OAuth token exchange + OpenAI-compatible chat completions streaming, no opencode CLI needed
• Google Antigravity direct API — Uses cloudcode-pa endpoint with automatic GCP project discovery (loadCodeAssist), transparent token refresh
• Dual execution model — CLI agents (Claude/Codex/Gemini) spawn local processes inheriting your environment; HTTP agents (Copilot/Antigravity) call APIs directly via OAuth
• Race condition fix — DB writes now happen synchronously before async HTTP agent launch
• Copilot token cache fix — Added sourceHash validation to prevent stale credentials after re-authentication
• SSE stream fixes — Final buffer flush, proper log stream await, negative PID handling for stop/delete

v1.0.1

• project_path first-class field — Cards now have a dedicated project_path column. Set it via UI, API (POST /api/cards, PATCH /api/cards/:id, POST /api/inbox), or AGENTS.md orchestration
• Run/review guard — Server blocks /run and /review when project_path is unset, preventing agents from running in the wrong directory
• 3-step fallback chain — card.project_path > description ## Project Path section > ask user (blocked)
• AGENTS.md orchestration updates — Orchestrator asks user for project path on card creation; checks for existing work before re-running; language-adaptive responses (Korean/English/auto-detect)
• Windows process management fix — killPidTree now uses execFile("taskkill") with timeout; kanban.mjs stop uses execSync("taskkill /T /F") for reliable process tree cleanup
• UI improvements — Project path input in card creation form and detail panel; "Save Description" renamed to "Save Details"; Working Dir shown in card metadata
• SQLite parameter binding fix — Explicit null conversion for all optional fields prevents undefined binding errors on node:sqlite

v1.0.0

• Initial release

License

Apache License 2.0 — see LICENSE for details.

Copyright 2025 GreenSheep01201