# Agent Board

> Open-source multi-agent task board for OpenClaw. Kanban + DAG dependencies + MCP server + auto-retry + audit trail. Built for autonomous AI agent teams.

- **Type:** MCP server
- **Install:** `agentstack add mcp-quentintou-agent-board`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [quentintou](https://agentstack.voostack.com/s/quentintou)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [quentintou](https://github.com/quentintou)
- **Source:** https://github.com/quentintou/agent-board
- **Website:** https://openclaw.ai

## Install

```sh
agentstack add mcp-quentintou-agent-board
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

🎯 Agent Board
  
    Multi-agent task orchestration for OpenClaw and AI agent teams.
    Kanban dashboard · REST API · MCP server · DAG dependencies · Auto-retry · Audit trail
  
  
    Features •
    Quick Start •
    OpenClaw Integration •
    API •
    MCP •
    Dashboard •
    Architecture
  
  
    
    
    
  

---

## Why Agent Board?

Running multiple AI agents without coordination is chaos. Each agent works in isolation, tasks get duplicated, failures go unnoticed, and there's no way to build multi-step workflows.

**Agent Board fixes this.** It's a task management system purpose-built for AI agent teams — whether you're running [OpenClaw](https://github.com/openclaw/openclaw) agents, Claude, or any LLM-based agents.

- **Agents pick up work** from the board via heartbeat polling or webhook notifications
- **Dependencies are enforced** — Agent B can't start until Agent A finishes
- **Failed tasks auto-retry** — no human intervention for transient failures
- **Task chaining** builds pipelines — when one agent finishes, the next one starts automatically
- **Full audit trail** — know exactly who did what, when, and why
- **MCP native** — agents interact through [Model Context Protocol](https://modelcontextprotocol.io/) tools

Works standalone or as the orchestration layer for an [OpenClaw](https://github.com/openclaw/openclaw) multi-agent setup.

## Features

| Feature | Description |
|---------|-------------|
| **Kanban Board** | 6 columns: `backlog` → `todo` → `doing` → `review` → `done` → `failed` |
| **DAG Dependencies** | Tasks can depend on other tasks. Moving to `doing` is blocked until all dependencies are `done`. Cycle detection prevents deadlocks. |
| **Quality Gates** | Mark tasks as `requiresReview: true` — they must pass through `review` before `done`. |
| **Auto-Retry** | When a task moves to `failed`, it automatically retries (back to `todo`) up to `maxRetries` times. System comments track each attempt. |
| **Task Chaining** | Define a `nextTask` on any task. When it completes, the next task is auto-created and assigned. Build pipelines without orchestration code. |
| **Real-Time Communication** | Task comment threads for agent-to-agent discussion. Webhooks fire on every event (comment, assign, move) — agents wake in seconds, not minutes. |
| **HMAC-SHA256 Signing** | All outbound webhooks are cryptographically signed. Receiving agents can verify message authenticity. Includes timestamp for replay protection. |
| **OpenClaw Webhooks** | Native [OpenClaw](https://github.com/openclaw/openclaw) webhook integration to wake agents when tasks are assigned, retried, or chained. |
| **Audit Trail** | Every action is logged to `audit.jsonl` — who did what, when, to which task. Queryable via API. Both REST and MCP mutations are tracked. |
| **Client View** | Read-only project dashboard for external stakeholders. Enable per-project with `clientViewEnabled`. Hides agent names and internal details. |
| **Project Templates** | Pre-define task sets as JSON templates. Apply them to any project in one call. |
| **Board Stats** | Per-agent and global statistics: completion rates, average duration, stuck task detection. |
| **MCP Server** | Full [Model Context Protocol](https://modelcontextprotocol.io/) server — AI agents manage tasks through 12 MCP tools. Compatible with Claude Desktop, Claude Code, and any MCP client. |
| **API Key Auth** | Optional per-agent API key authentication. Backward-compatible (no keys = no auth). |
| **Zod Validation** | All inputs validated with Zod schemas. Clear error messages on invalid requests. |
| **Concurrent Safety** | Per-file async mutex locking on all writes. Atomic temp-file-then-rename. No corruption under concurrent access. |
| **Auto-Backup** | Automatic backups before every write (up to 50 per file, auto-pruned). |

## Quick Start

```bash
git clone https://github.com/quentintou/agent-board.git
cd agent-board
npm install
npm run build
npm start
```

Open **http://localhost:3456** for the Kanban dashboard, or hit **http://localhost:3456/api** for the REST API.

### Options

```bash
node dist/index.js --port 8080 --data ./my-data
```

| Flag | Default | Description |
|------|---------|-------------|
| `--port` | `3456` | HTTP server port |
| `--data` | `./data` | Directory for JSON data files |

### Environment Variables

| Variable | Description |
|----------|-------------|
| `AGENTBOARD_API_KEYS` | Comma-separated `key:agentId` pairs for API authentication. Example: `sk-abc123:agent1,sk-def456:agent2` |
| `OPENCLAW_HOOK_URL` | OpenClaw webhook URL for agent notifications (default: `http://localhost:18789/hooks/agent`) |
| `OPENCLAW_HOOK_TOKEN` | Bearer token for OpenClaw webhook calls. Notifications disabled if not set. |
| `AGENTBOARD_WEBHOOK_SECRET` | Secret for HMAC-SHA256 webhook signing. When set, all outbound webhooks include `X-AgentBoard-Signature` headers. |
| `TEMPLATES_DIR` | Custom templates directory (default: `./templates`) |

## Real-Time Agent Communication

Agent Board v2 enables **real-time inter-agent communication** through task threads and signed webhooks:

### Task Threads
Agents discuss work directly on tasks — like GitHub issue comments, but for AI agents:

```bash
# Agent posts an update
curl -X POST http://localhost:3456/api/tasks/task_abc/comments \
  -H "Content-Type: application/json" \
  -d '{"author":"research-agent","text":"Found 3 competitor gaps. See analysis in output."}'

# Other agents read the thread
curl http://localhost:3456/api/tasks/task_abc/comments
```

Every comment triggers a webhook to the task assignee — waking them instantly with their full model (not a lightweight heartbeat model).

### Signed Webhooks (HMAC-SHA256)
All outbound webhooks include cryptographic signatures for trust verification:

```
X-AgentBoard-Signature: sha256=a1b2c3...
X-AgentBoard-Timestamp: 1770307200000
X-AgentBoard-Source: agentboard
```

Set `AGENTBOARD_WEBHOOK_SECRET` to enable signing. Receiving agents verify with the included `shared/verify-webhook.sh` utility.

### Event Types
Webhooks fire on all significant events:
- **comment.add** — New comment on a task → assignee wakes up
- **task.assign** — Assignee changed → new assignee notified
- **task.move** — Task moved to `doing`, `review`, or `failed` → assignee notified
- **task.create** — High/urgent task created → assignee wakes up immediately

### MCP Comment Tools
AI agents manage threads through MCP — no HTTP needed:
- `board_list_comments` — Read a task's comment thread
- `board_add_comment` — Post to a task thread
- `board_get_task_thread` — Get full task context + all comments

## OpenClaw Integration

Agent Board is designed as the **orchestration layer for [OpenClaw](https://github.com/openclaw/openclaw) multi-agent setups**. Here's how they work together:

### Architecture: OpenClaw + Agent Board

```
┌─────────────────────────────────────────────────┐
│                  OpenClaw Gateway                │
│                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ Agent A  │ │ Agent B  │ │ Agent C          │ │
│  │ (Sonnet) │ │ (Opus)   │ │ (Gemini Flash)   │ │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│       │             │                │           │
│       └─────────────┴────────────────┘           │
│                     │                            │
│            ┌────────▼────────┐                   │
│            │   Agent Board   │ ◄── REST / MCP    │
│            │   (localhost)   │                    │
│            └─────────────────┘                   │
└─────────────────────────────────────────────────┘
```

### How Agents Use the Board

1. **Heartbeat polling** — Each OpenClaw agent checks the board periodically (via `curl` or MCP tools) for assigned tasks
2. **Webhook wake** — When a high-priority task is created, Agent Board sends a webhook to OpenClaw's `/hooks/agent` endpoint, which wakes the target agent immediately
3. **Task lifecycle** — Agents move tasks through columns: pick up from `todo` → work in `doing` → submit to `review` or `done`
4. **Auto-chaining** — When Agent A completes a task with `nextTask` defined, the follow-up task is auto-created and assigned to Agent B

### OpenClaw Agent HEARTBEAT.md Example

Add this to your OpenClaw agent's `HEARTBEAT.md`:

```markdown
### Board Check
Check for assigned tasks:
curl -s http://localhost:3456/api/tasks?assignee=my-agent-id&status=todo | jq
If tasks found, pick the highest priority one and start working.
```

### OpenClaw Configuration

Set the webhook token in your Agent Board service to match your OpenClaw hooks token:

```bash
OPENCLAW_HOOK_URL=http://localhost:18789/hooks/agent
OPENCLAW_HOOK_TOKEN=your-openclaw-hooks-token
```

Agent Board maps agent IDs to OpenClaw session keys (configurable in `routes.ts`).

## Dashboard

The web dashboard at `http://localhost:3456` provides:

- **Kanban board** with drag-and-drop between columns
- **Project selector** and creation
- **Task creation** with all fields (priority, tags, dependencies, deadlines, review gates)
- **Task detail view** with comments, metrics, and dependency graph
- **Agent overview** with performance stats
- **Dark/light theme** toggle
- **Auto-refresh** every 5 seconds

### Client View

Enable `clientViewEnabled` on a project to get a read-only dashboard at:

```
http://localhost:3456/dashboard/client/:projectId
```

Client view hides agent names and internal details — safe to share with external stakeholders.

## API Reference

Base URL: `http://localhost:3456/api`

### Authentication

If `AGENTBOARD_API_KEYS` is set, all requests require an `X-API-Key` header:

```bash
curl -H "X-API-Key: sk-abc123" http://localhost:3456/api/projects
```

If no keys are configured, all requests are allowed (backward compatible).

### Health

```
GET /api/health → { "status": "ok", "uptime": 3600, "timestamp": "..." }
```

### Projects

```http
GET    /api/projects                       # List projects (?status=active&owner=alice)
GET    /api/projects/:id                   # Get project + its tasks
POST   /api/projects                       # Create project
PATCH  /api/projects/:id                   # Update project fields
DELETE /api/projects/:id                   # Delete project + all its tasks
```

**Create project:**
```json
{
  "name": "Website Redesign",
  "owner": "agency",
  "description": "Full site rebuild",
  "clientViewEnabled": true
}
```

### Tasks

```http
GET    /api/tasks                          # List tasks (?projectId=&assignee=&status=&tag=)
GET    /api/tasks/:id                      # Get single task
POST   /api/tasks                          # Create task
PATCH  /api/tasks/:id                      # Update task fields
DELETE /api/tasks/:id                      # Delete task (cleans up orphaned deps)
POST   /api/tasks/:id/move                 # Move to column (enforces DAG + gates)
POST   /api/tasks/:id/comments             # Add comment (triggers webhook)
GET    /api/tasks/:id/comments             # List comments
GET    /api/tasks/:id/dependencies         # List dependencies and blockers
GET    /api/tasks/:id/dependents           # List tasks depending on this one
```

**Create task with chaining and dependencies:**
```json
{
  "projectId": "proj_abc123",
  "title": "Write landing page copy",
  "assignee": "content-creator",
  "priority": "high",
  "tags": ["copywriting"],
  "dependencies": ["task_xyz789"],
  "requiresReview": true,
  "maxRetries": 3,
  "nextTask": {
    "title": "Design landing page",
    "assignee": "design-agent",
    "priority": "high"
  }
}
```

**Move task:** `POST /api/tasks/:id/move` with `{ "column": "doing" }`

Columns: `backlog` · `todo` · `doing` · `review` · `done` · `failed`

### Templates

```http
GET    /api/templates                      # List available templates
POST   /api/projects/:id/from-template     # Apply template to project
```

```json
{ "template": "seo-audit" }
```

### Agents

```http
GET    /api/agents                         # List registered agents
POST   /api/agents                         # Register agent (409 if exists)
```

### Stats

```http
GET /api/stats                             # Board + per-agent statistics
```

Returns completion rates, average task duration, stuck task detection, and per-agent performance metrics.

### Audit Trail

```http
GET /api/audit                             # ?taskId=&agentId=&limit=100
```

Returns append-only log entries (newest first) for all REST and MCP mutations.

### Client View

```http
GET /api/client/:projectId                 # Read-only sanitized project data
```

## MCP Server

Agent Board includes a full [Model Context Protocol](https://modelcontextprotocol.io/) server for AI agent integration. Agents can manage tasks through natural MCP tool calls — no HTTP client needed.

```bash
npm run mcp                                # default data dir
node dist/mcp-server.js --data ./data      # custom data dir
```

### Claude Desktop / Claude Code Configuration

```json
{
  "mcpServers": {
    "agent-board": {
      "command": "node",
      "args": [
        "/path/to/agent-board/dist/mcp-server.js",
        "--data", "/path/to/agent-board/data"
      ]
    }
  }
}
```

### MCP Tools (12)

| Tool | Description |
|------|-------------|
| `board_list_projects` | List projects (filter by `status`, `owner`) |
| `board_get_project` | Get project details + all tasks |
| `board_create_project` | Create a new project |
| `board_update_project` | Update project fields |
| `board_create_task` | Create a task with full options (deps, chaining, gates) |
| `board_update_task` | Update task fields |
| `board_move_task` | Move task to a column (enforces deps + quality gates) |
| `board_add_comment` | Add a comment to a task |
| `board_list_tasks` | List tasks with filters |
| `board_my_tasks` | Get all tasks for a specific agent |
| `board_delete_task` | Delete a task |
| `board_list_comments` | List comments on a task |
| `board_get_task_thread` | Get task summary + full comment thread |
| `board_delete_project` | Delete a project and all its tasks |

All MCP mutations are logged to the audit trail.

## Architecture

```
agent-board/
├── src/
│   ├── index.ts          # Express server, CLI args, static files
│   ├── routes.ts         # REST API routes, auth middleware, OpenClaw webhooks
│   ├── services.ts       # Business logic (move with deps/gates/retry/chain)
│   ├── store.ts          # JSON file storage with async mutex + atomic writes
│   ├── schemas.ts        # Zod validation schemas
│   ├── audit.ts          # Append-only JSONL audit log
│   ├── types.ts          # TypeScript interfaces
│   ├── utils.ts          # ID generation, timestamp helpers
│   └── mcp-server.ts     # MCP stdio server (12 tools)
├── dashboard/
│   ├── index.html        # Kanban dashboard (drag-and-drop)
│   ├── client.html       # Read-only client view
│   ├── app.js            # Dashboard logic
│   └── style.css         # Dark/light theme
├── templates/            # Reusable task templates (JSON)
├── shared/               # Webhook verification utility
├── tests/                # 107 tests (Vitest)
└── data/                 # Runtime data (auto-created, gitignored)
```

### Data Flow

```
Agent (REST/MCP) → Auth → Zod Validation → Service Layer → Store (mutex lock)
                                                │
                                                ├── DAG dependency check
                                                ├── Quality gate enforcement
                                                ├── Auto-retry on failure
                                                ├── Task chaining on completion
                                                ├── Audit log append
                                                └── OpenClaw webhook → Agent wakes up
```

### Design Decisions

- **Zero external database** — JSON files with atomic writes. Simple to deploy, backup, inspect,

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [quentintou](https://github.com/quentintou)
- **Source:** [quentintou/agent-board](https://github.com/quentintou/agent-board)
- **License:** MIT
- **Homepage:** https://openclaw.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-quentintou-agent-board
- Seller: https://agentstack.voostack.com/s/quentintou
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.