🎯 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 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 tools

Works standalone or as the orchestration layer for an 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 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 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

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

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:

# 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 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:

### 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:

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:

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

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:

{
  "name": "Website Redesign",
  "owner": "agency",
  "description": "Full site rebuild",
  "clientViewEnabled": true
}

Tasks

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:

{
  "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

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

{ "template": "seo-audit" }

Agents

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

Stats

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

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

Audit Trail

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

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

Client View

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

MCP Server

Agent Board includes a full Model Context Protocol server for AI agent integration. Agents can manage tasks through natural MCP tool calls — no HTTP client needed.

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

Claude Desktop / Claude Code Configuration

{
  "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, and version control.
• Per-file async mutex — Concurrent API calls never corrupt data, without needing PostgreSQL or Redis.
• MCP-first — AI agents interact through MCP tools naturally. No SDK, no client library.
• OpenClaw-native webhooks — Agents get woken up instantly when tasks need attention. Works with any webhook consumer.
• Security hardened — Path traversal protection, circular dependency detection, input validation on all routes, audit trail on all mutations.

Running as a Service

systemd

[Unit]
Description=Agent Board - Multi-agent task orchestration
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/agent-board
ExecStart=/usr/bin/node dist/index.js --port 3456 --data ./data
Environment=AGENTBOARD_API_KEYS=sk-key1:agent1,sk-key2:agent2
Environment=OPENCLAW_HOOK_TOKEN=your-token
Restart=on-failure

[Install]
WantedBy=multi-user.target

Docker

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist/ dist/
COPY dashboard/ dashboard/
COPY templates/ templates/
EXPOSE 3456
CMD ["node", "dist/index.js"]

Development

npm install              # Install dependencies
npm run build            # Compile TypeScript
npm run dev              # TypeScript watch mode
npm test                 # Run all 92 tests (Vitest)

Tech Stack

• Runtime: Node.js + Express
• Language: TypeScript
• Validation: Zod
• MCP: @modelcontextprotocol/sdk
• Tests: Vitest + Supertest (107 tests)
• Dashboard: Vanilla HTML/CSS/JS (no build step)
• Storage: JSON files (no database required)

Contributing

Issues and PRs welcome. Please run npm test before submitting.

License

MIT

---

Built for AI agent teams. Works great with OpenClaw.
openclaw.ai · Discord