claude-kanban 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# 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
+
+```bash
+# 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
+
+```bash
+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:
+```bash
+./scripts/ralph.sh 10  # Run 10 iterations
+```
+
+**ralph-once.sh** - Run a single iteration:
+```bash
+./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:
+
+```json
+{
+  "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](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
+
+## License
+
+MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node