Claw Machine
A web-based kanban board for orchestrating Claude Code workers via claude-team and OpenClaw.
Installation
npx claw-machineAsk AI about Claw Machine
Powered by Claude Β· Grounded in docs
I know everything about Claw Machine. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Claw Machine
A web-based kanban board for orchestrating Claude Code workers via claude-team and OpenClaw. Built mostly by OpenClaw and Claude Opus 4.5 using the kanban interface itself (meta!).
Overview
Claw Machine is a full-stack task management application that lets you visually manage tasks and automatically spawn Claude Code workers to complete them. Think Trello/Linear but with AI workers that actually do the work. An OpenClaw agent (with per-project sessions) is used as the reviewer and merger once tasks are complete.
Installation & Setup
Prerequisites
- Bun (>= 1.0)
- claude-team MCP server running on
http://127.0.0.1:8766/mcp - PM2 (optional, for production)
- OpenClaw (for automated code review and merging)
Backend Setup
cd backend
bun install
bun run dev # Development mode with hot reload
# or
bun run start # Production mode
Frontend Setup
cd frontend
bun install
bun run dev # Development server on port 5173
# or
bun run build # Production build
OpenClaw Integration Setup
To set up automated code review notifications when workers complete tasks:
1. Install the claude-team Skill
# Install the claude-team skill for OpenClaw
npx clawhub@latest install claude-team
Then go ask your main OpenClaw agent to make sure the claude-team skill is setup (it probably needs to set up the claude-team MCP server and install some stuff).
2. Configure the Reviewer Agent
Edit your ~/.openclaw/openclaw.json to add the reviewer agent, enable hooks,
and set the gateway hooks API token.
It should look something like this:
{
"agents": {
"list": [
{
"id": "main",
"sandbox": {
"mode": "off"
}
},
{
"id": "reviewer",
"sandbox": {
"mode": "off"
}
}
]
},
"hooks": {
"enabled": true,
"token": "<your-gateway-token>"
}
}
Important:
- The
mainagent must be included to keep the default main agent separate - The
revieweragent will receive notifications when workers complete tasks - Generate a secure random token for
hooks.token
Environment Variables
Backend (backend/.env):
PORT=18800 # API server port
HOST=0.0.0.0 # Bind address
AUTH_PASSWORD=your-password # Auth password (default: claw-machine-2026)
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789 # OpenClaw gateway
OPENCLAW_TOKEN=your-token # OpenClaw auth token
CLAUDE_TEAM_MCP_URL=http://127.0.0.1:8766/mcp # claude-team MCP server
Frontend (frontend/.env):
VITE_API_URL=http://localhost:18800 # Backend API URL
Production Deployment with PM2
# From project root
pm2 start ecosystem.config.js
# View logs
pm2 logs
# Restart services
pm2 reload claw-machine-backend
pm2 reload claw-machine-frontend
# Stop services
pm2 stop claw-machine-backend claw-machine-frontend
Usage
- Login: Enter the auth password (default:
claw-machine-2026) - Create a project: Click the project selector and add a new project path
- Create tasks: Click "+" in the Backlog column, enter title and description
- Spawn workers: Drag a task from Backlog to In Progress
- A Claude Code worker spawns automatically in a git worktree
- Watch progress in the Worker Panel
- View live logs by clicking "View Logs" on the worker or task
- Review work: When the worker goes idle (task complete):
- Task moves to "reviewing" state
- OpenClaw gateway sends a notification (if configured)
- Review the git diff in the worker's worktree
- Move task to Done when satisfied (auto-closes worker)
- Pause/Resume: Drag In Progress tasks back to Backlog
- Worker closes automatically
- Conversation context is preserved for next spawn
Features
Kanban Board
- Three-column workflow: Backlog β In Progress β Done
- Drag-and-drop: Move tasks between columns with smooth animations
- Project filtering: Filter tasks by project or view all at once
- Real-time updates: WebSocket-powered live sync across all clients
- Mobile responsive: Works seamlessly on desktop, tablet, and mobile
Worker Management
- Automatic spawning: Drag a task to "In Progress" to spawn a Claude Code worker
- Worker panel: Real-time view of all active workers with status indicators
- Log streaming: Live worker conversation logs with incremental updates
- Git worktrees: Each worker runs in an isolated git worktree
- Smart cleanup: Workers auto-close when tasks move to Done or back to Backlog
- Review notifications: OpenClaw gateway integration for human-in-the-loop review
Task Features
- Rich metadata: Title, description, timestamps (created, started, completed)
- Worker context: Preserve conversation history when pausing/resuming tasks
- Status tracking: Visual indicators for worker states (starting, running, reviewing, closed)
- Edit mode: Edit title and description for backlog tasks
- Task logs: View full conversation history in a modal viewer
Project Management
- Multi-project support: Organize tasks by filesystem project path
- Auto-discovery: Create projects by providing a valid directory path
- Default project: Smart selection for new task creation
- Project selector: Quick filter and switch between projects
Tech Stack
Backend
- Runtime: Bun (fast JavaScript runtime)
- Framework: Hono (lightweight, fast HTTP framework)
- Database: SQLite (via bun:sqlite)
- Real-time: Native WebSocket support
- MCP Client: @modelcontextprotocol/sdk for claude-team integration
- Process Manager: PM2 for production deployment
Frontend
- Framework: React 19 + TypeScript
- Build Tool: Vite
- Styling: Tailwind CSS 4
- Drag & Drop: @dnd-kit
- State Management: React hooks + custom API hooks
Infrastructure
- Authentication: Bearer token password protection
- CORS: Configured for multi-origin access
- Polling: Smart worker status polling (2s) and log streaming (3s)
- Git Worktrees: Isolated development environments per worker
Architecture
βββββββββββββββββββββββ
β React Frontend β
β (Vite + Tailwind) β
ββββββββββββ¬βββββββββββ
β HTTP REST API
β WebSocket
ββββββββββββΌβββββββββββ
β Bun + Hono API β
β (Port 18800) β
ββββββββββββ¬βββββββββββ
β MCP HTTP Transport
ββββββββββββΌβββββββββββ
β claude-team Server β
β (Port 8766/mcp) β
ββββββββββββ¬βββββββββββ
β Spawns/manages
ββββββββββββΌβββββββββββ
β Claude Code Workersβ
β (Git worktrees) β
βββββββββββββββββββββββ
API Endpoints
Tasks
GET /api/tasks?project_id=<id>- List tasks (optionally filter by project)GET /api/tasks/:id- Get single taskPOST /api/tasks- Create task (requirestitle,projectId; spawns worker ifstatus: "in_progress")PATCH /api/tasks/:id- Update task (handles worker spawn/close automatically on status change)POST /api/tasks/:id/respawn- Respawn worker for in-progress task (saves context, closes old worker, spawns new)DELETE /api/tasks/:id- Delete task
Workers
GET /api/workers- List all workers (enriched with task info)POST /api/workers/:id/close- Close a worker manually
Projects
GET /api/projects- List all projectsPOST /api/projects- Create project (requirespath)PATCH /api/projects/:id- Update project pathDELETE /api/projects/:id- Delete project
WebSocket
WS /ws- Real-time updates for tasks and workerstasks_update- Full task list syncworkers_update- Full worker list syncping/pong- Keep-alive
Worker Lifecycle
Backlog Task
β
βΌ (drag to In Progress)
Worker Spawning (status: "starting")
β
βΌ
Worker Running (status: "running")
β
βΌ (worker goes idle)
Worker Reviewing (status: "reviewing")
β
βββΆ (drag to Done) β Worker Closed
βββΆ (drag to Backlog) β Worker Closed + Context Saved
βββΆ (POST /respawn) β Worker Closed + Context Saved + New Worker Spawned
Database Schema
Tasks Table
id(TEXT, PK) - UUIDtitle(TEXT) - Task titledescription(TEXT) - Task descriptionstatus(TEXT) - backlog | in_progress | doneassigned_worker(TEXT) - Worker IDworker_status(TEXT) - starting | running | reviewing | closedworker_context(TEXT) - Saved conversation contextlogs(TEXT) - JSON array of WorkerLog objectsproject_id(TEXT, FK) - Reference to projects tablecreated_at(TEXT) - ISO timestampupdated_at(TEXT) - ISO timestampstarted_at(TEXT) - When moved to in_progresscompleted_at(TEXT) - When moved to done
Projects Table
id(TEXT, PK) - UUIDpath(TEXT, UNIQUE) - Filesystem pathname(TEXT) - Display name (basename of path)created_at(TEXT) - ISO timestamp
Integration with OpenClaw
When a worker completes a task (goes idle), the backend can notify OpenClaw gateway to wake a reviewer agent:
POST ${OPENCLAW_GATEWAY}/hooks/agent
Content-Type: application/json
Authorization: Bearer ${OPENCLAW_TOKEN}
{
"name": "[Reviewer] Task Title",
"sessionKey": "project-id",
"agentId": "reviewer",
"wakeMode": "now",
"message": "Worker ${worker.name} completed task: ${task.title}..."
}
The reviewer agent receives instructions on how to:
- Read worker logs via
mcporter - Check the git diff
- Merge or request changes
- Mark task as done via API
Development Notes
Worker Spawning
- Workers spawn with
use_worktree: truefor isolation - Each worker gets a unique annotation:
task-{taskId} - Initial prompt includes task title, description, and worktree setup instructions
Log Streaming
- Logs are fetched incrementally every 3 seconds
- Only active/busy/idle workers are polled
- claude-team session markers are automatically stripped
- Logs are cached to task when worker goes idle or task moves to done
Status Polling
- Worker status polled every 2 seconds
- Idle detection triggers reviewing state and OpenClaw notification
- Changes broadcast via WebSocket only when state changes
Authentication
- Simple Bearer token authentication
- Password stored in localStorage on frontend
- All API requests (except
/health) require auth header
Credits
Built mostly by OpenClaw and Claude Opus 4.5, using the kanban interface itself to orchestrate the development. Every feature was implemented by AI workers managed through this very tool.
