claudeboard 2.16.0 → 3.1.0

package/README.md

@@ -1,128 +1,124 @@
-# ClaudeBoard 🤖
+# ClaudeBoard v3
 
-**Autonomous coding dashboard for Claude Code.**  
-Turn a PRD into tasks → let Claude work autonomously → watch progress in real time.
+Visual orchestrator for Claude Code agent teams. Run and manage multiple Claude Code agents from a single browser-based kanban dashboard.
 
----
+## What it does
 
-## How it works
+ClaudeBoard launches a local web server and opens a dashboard where you can:
+- Chat with an Orchestrator agent that interviews you, generates a PRD, and breaks work into tasks
+- Watch tasks move through a Kanban board (Backlog → In Progress → Verifying → Done / Error)
+- Stream live agent output in a built-in terminal drawer
+- Receive webhook notifications when tasks complete or fail
+
+## Requirements
+
+- Node.js >= 18
+- Claude CLI installed and logged in (`claude --version` should work)
+
+## Installation
+
+Run without installing:
 
 ```
-claudeboard init          → Configure project + Supabase
-claudeboard import-prd    → Parse PRD → create tasks automatically
-claudeboard start         → Launch dashboard on localhost
-                          → Give Claude Code the AGENT.md file
-                          → Claude works autonomously 24/7
+npx claudeboard
 ```
 
----
-
-## Install
+Or install globally:
 
-```bash
+```
 npm install -g claudeboard
+claudeboard
 ```
 
----
+## Usage
 
-## Setup (one time per project)
-
-### 1. Init
-```bash
-cd your-project
-claudeboard init
 ```
-You'll be asked for:
-- Project name
-- Supabase URL
-- Supabase anon key
-- Port (default 3131)
-
-### 2. Run SQL in Supabase
-Open `claudeboard-setup.sql` and run it in your Supabase SQL Editor.  
-This creates the tables `cb_epics`, `cb_tasks`, `cb_logs` with Realtime enabled.
-
-### 3. Import your PRD
-```bash
-claudeboard import-prd ./PRD.md
+claudeboard [options]
 ```
-Claude parses your PRD and creates structured tasks grouped by epic automatically.
 
-### 4. Start the dashboard
-```bash
-claudeboard start
-```
-Opens `http://localhost:3131` in your browser.
+### CLI Flags
 
----
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port <number>` | `3000` | Port to run the dashboard server on |
+| `--open <bool>` | `true` | Automatically open the dashboard in your browser |
+| `--webhook <url>` | — | Webhook URL (must be `https://`) to POST agent lifecycle events to |
+| `--max-agents <number>` | `3` | Maximum number of agents allowed to run concurrently |
 
-## Running Claude Code autonomously
+### Examples
 
-```bash
-claude --context AGENT.md
 ```
+# Start on default port, auto-open browser
+claudeboard
 
-The `AGENT.md` file (auto-generated by `claudeboard init`) tells Claude to:
-1. Fetch the next pending task from the API
-2. Start it → mark as `in_progress`
-3. Do the work (write code, run tests, fix errors)
-4. Log progress in real time
-5. Mark as `done` or `error`
-6. Repeat until all tasks are complete
+# Use a custom port without auto-opening
+claudeboard --port 4000 --open false
 
----
+# Limit to 5 concurrent agents and send events to a webhook
+claudeboard --max-agents 5 --webhook https://example.com/hooks/claudeboard
+```
 
-## Dashboard features
+## How it works
 
-- **Kanban view** — tasks grouped by epic with status colors
-- **Live activity log** — every action Claude takes
-- **Progress bar** — overall completion %
-- **Add tasks** — add new tasks manually (Claude picks them up automatically)
-- **Task detail** — click any task to see its full log
-- **Real-time** — WebSocket updates, no refresh needed
+1. Start ClaudeBoard — a local Express server starts and the dashboard opens in your browser.
+2. The Orchestrator agent greets you and asks what you want to build.
+3. After 2–3 exchanges it generates a PRD and populates the Kanban board with tasks.
+4. Claude Code sub-agents are spawned automatically (respecting `--max-agents`).
+5. Each agent's output streams live to the task card in the dashboard.
+6. A Verifier agent checks each completed task — approved tasks move to Done; failed tasks spawn a Fix task.
 
----
+## Project data
 
-## API (used by Claude Code)
+ClaudeBoard stores all state in `.claudeboard/` inside your working directory:
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/board` | Full board state |
-| GET | `/api/tasks/next` | Next pending task |
-| POST | `/api/tasks/:id/start` | Mark task as in_progress |
-| POST | `/api/tasks/:id/log` | Add a log entry |
-| POST | `/api/tasks/:id/complete` | Mark task as done |
-| POST | `/api/tasks/:id/fail` | Mark task as error |
-| POST | `/api/tasks` | Add a new task |
-| GET | `/api/tasks/:id/logs` | Get logs for a task |
+| File | Contents |
+|------|----------|
+| `.claudeboard/tasks.json` | Task list and status |
+| `.claudeboard/prd.md` | Generated PRD |
+| `.claudeboard/agents.json` | Active agent registry |
+| `.claudeboard/config.json` | Board configuration (webhook URL, etc.) |
 
----
+**Add `.claudeboard/` to your `.gitignore`** — it may contain webhook URLs and agent output that should not be committed.
 
-## Remote access
+## Security
 
-To monitor from another computer:
+ClaudeBoard is designed to be safe to run on a shared development machine.
 
-```bash
-# On the notebook running claudeboard:
-# Install Tailscale: https://tailscale.com
-tailscale up
+### Localhost-only server
 
-# Then from your main computer:
-# Visit http://<notebook-tailscale-ip>:3131
-```
+The server **only** binds to `127.0.0.1` (loopback). It is never reachable from the network or other machines on the same LAN.
 
-Or with SSH tunnel:
-```bash
-ssh -L 3131:localhost:3131 user@notebook-ip
-# Then open http://localhost:3131 locally
-```
+### No external data transmission
+
+ClaudeBoard sends **no data to any external service**. The only outbound network calls are:
+
+- Calls to the `claude` CLI (uses your existing local session — no API key required)
+- Optional webhook `POST` requests to a URL **you** configure with `--webhook`
+
+Webhook URLs must be `https://` and calls time out after 5 seconds.
+
+### Subprocess safety
+
+All `claude` CLI invocations use `spawn()` with an explicit argument array (`shell: false`). Prompts are delivered via stdin, not command-line arguments, so they never appear in process listings and there is no shell-injection risk regardless of what the user types.
+
+### Input sanitization & rate limiting
+
+- User chat messages are stripped of null bytes and capped at 10,000 characters before reaching the CLI.
+- WebSocket connections are rate-limited to 10 messages per second per client.
+- Task IDs are validated against a strict alphanumeric pattern before any file or process operations.
+
+### Agent output cap
+
+Agent output stored to disk is capped at **1 MB per task** to prevent runaway processes from filling the disk.
+
+### Session-based auth
+
+Access to the dashboard requires access to `127.0.0.1` (i.e., you must be logged in to the machine). There is no additional authentication layer — treat it like any other local dev tool.
+
+### Reporting vulnerabilities
 
----
+Please open a GitHub issue with the `[SECURITY]` tag. Do **not** include exploit details in a public issue — reach out privately first.
 
-## Stack
+## License
 
-- **CLI**: Node.js + Commander + Enquirer
-- **Server**: Express + WebSockets
-- **Database**: Supabase (Postgres + Realtime)
-- **Dashboard**: Vanilla HTML/CSS/JS (no build step)
-- **AI parsing**: Claude claude-sonnet-4-20250514 for PRD analysis
+MIT