Claude Kanban

A visual Kanban board for AI-powered development with Claude. Run npx claude-kanban in any project directory to manage and execute AI coding tasks.

Features

• Visual Kanban Board: Drag-and-drop tasks across columns (Draft, Ready, In Progress, Completed)
• AI Task Execution: Click to run tasks with Claude Code CLI
• Real-time Updates: WebSocket streaming of execution output
• Parallel Execution: Run up to 3 tasks concurrently
• AFK Mode: Automated loop execution for hands-off development
• AI Task Generation: Describe what you want, get structured tasks
• Task Templates: Pre-built templates for common patterns

Installation

# Run directly with npx (no installation needed)
npx claude-kanban

# Or install globally
npm install -g claude-kanban
claude-kanban

Requirements

• Node.js 18+
• Claude Code CLI (claude) installed and configured

Usage

Quick Start

cd your-project
npx claude-kanban

This will:

1. Create .claude-kanban/ directory with config files
2. Create scripts/ralph.sh and scripts/ralph-once.sh
3. Start a local web server
4. Open your browser to the Kanban board

CLI Options

Usage: claude-kanban [options]

Options:
  -V, --version        output the version number
  -p, --port <number>  Port to run server on (default: "4242")
  -n, --no-open        Do not auto-open browser
  --init               Re-initialize project files
  --reset              Reset all tasks (keeps config)
  -h, --help           display help for command

Creating Tasks

Manual: Click "+ New" to create a task with title, description, and verification steps.

AI-Assisted: Click "AI Create", describe what you want, and Claude generates structured task details.

Templates: Click "Templates" to use pre-built patterns for auth, CRUD, API endpoints, etc.

Running Tasks

1. Move tasks from "Draft" to "Ready" when requirements are clear
2. Click "Run" on a Ready task to execute with Claude
3. Watch real-time output in the execution log
4. Task automatically moves to "Completed" on success or shows "Failed" status

AFK Mode

Click "AFK" to run multiple iterations automatically:

• Set maximum iterations
• Set concurrent task limit (1-3)
• Agent picks up tasks from "Ready" column
• Continue until all tasks complete or max iterations reached

Shell Scripts

The tool generates shell scripts for CLI usage:

ralph.sh - Run multiple iterations:

./scripts/ralph.sh 10  # Run 10 iterations

ralph-once.sh - Run a single iteration:

./scripts/ralph-once.sh              # Pick highest priority task
./scripts/ralph-once.sh task_abc123  # Run specific task

Project Structure

your-project/
├── .claude-kanban/
│   ├── prd.json         # Task list (Product Requirements Document)
│   ├── progress.txt     # Agent memory/progress log
│   └── config.json      # Configuration
└── scripts/
    ├── ralph.sh         # AFK automation script
    └── ralph-once.sh    # Single-run script

Configuration

Edit .claude-kanban/config.json to customize:

{
  "agent": {
    "command": "claude",
    "permissionMode": "acceptedits",
    "model": null
  },
  "project": {
    "testCommand": "npm test",
    "typecheckCommand": "npm run typecheck",
    "buildCommand": "npm run build"
  },
  "execution": {
    "maxConcurrent": 3,
    "timeout": 30
  }
}

API Reference

The server exposes a REST API:

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/tasks | Get all tasks | | POST | /api/tasks | Create task | | POST | /api/tasks/generate | AI-generate task | | PUT | /api/tasks/:id | Update task | | DELETE | /api/tasks/:id | Delete task | | POST | /api/tasks/:id/run | Run task | | POST | /api/tasks/:id/cancel | Cancel task | | GET | /api/templates | Get templates | | POST | /api/afk/start | Start AFK mode | | POST | /api/afk/stop | Stop AFK mode |

WebSocket events stream execution output in real-time.

Methodology

This tool implements the "Ralph" methodology for AI coding agents:

1. Small Tasks: Keep tasks focused and atomic
2. Incremental Progress: One feature per iteration
3. Progress Tracking: Maintain a log between sessions
4. Git Commits: Checkpoint work after each task
5. Feedback Loops: Use tests and type checking

Based on Anthropic's research on effective harnesses for long-running agents.

License

MIT