🎯 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

Heartbeat polling — Each OpenClaw agent checks the board periodically (via curl or MCP tools) for assigned tasks
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
Task lifecycle — Agents move tasks through columns: pick up from todo → work in doing → submit to review or done
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

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
dashboard		dashboard
shared		shared
src		src
templates		templates
tests		tests
workflows		workflows
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

quentintou/agent-board

Folders and files

Latest commit

History

Repository files navigation

🎯 Agent Board

Why Agent Board?

Features

Quick Start

Options

Environment Variables

Real-Time Agent Communication

Task Threads

Signed Webhooks (HMAC-SHA256)

Event Types

MCP Comment Tools

OpenClaw Integration

Architecture: OpenClaw + Agent Board

How Agents Use the Board

OpenClaw Agent HEARTBEAT.md Example

OpenClaw Configuration

Dashboard

Client View

API Reference

Authentication

Health

Projects

Tasks

Templates

Agents

Stats

Audit Trail

Client View

MCP Server

Claude Desktop / Claude Code Configuration

MCP Tools (12)

Architecture

Data Flow

Design Decisions

Running as a Service

systemd

Docker

Development

Tech Stack

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages