ClawTeam-OpenClaw — Multi-Agent Swarm Coordination

---
name: clawteam-openclaw-swarm
description: Multi-agent swarm coordination with OpenClaw as default agent — spawn, coordinate, and monitor CLI agent teams using git worktrees and tmux
triggers:
  - use clawteam to coordinate agents
  - spawn multiple agents to work in parallel
  - set up a multi-agent swarm
  - coordinate AI agents across tasks
  - use openclaw with clawteam
  - split work across multiple coding agents
  - launch an agent team for this project
  - orchestrate agents with clawteam
---

# ClawTeam-OpenClaw — Multi-Agent Swarm Coordination

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

ClawTeam-OpenClaw is a fork of [HKUDS/ClawTeam](https://github.com/HKUDS/ClawTeam) that turns CLI coding agents (OpenClaw, Claude Code, Codex, nanobot) into self-organizing swarms. A leader agent spawns workers, assigns tasks with dependency chains, coordinates via inbox messaging, and merges results — all through a single `clawteam` CLI. Each worker gets an isolated git worktree and tmux window.

---

## Installation

### Prerequisites

```bash
python3 --version   # Need 3.10+
tmux -V             # Any version
openclaw --version  # Or: claude --version / codex --version

Install missing tools:

# macOS
brew install python@3.12 tmux
pip install openclaw

# Ubuntu/Debian
sudo apt update && sudo apt install python3 python3-pip tmux
pip install openclaw

Install ClawTeam-OpenClaw

Do NOT use pip install clawteam — that installs the upstream version without OpenClaw support.

git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
pip install -e .

# Optional: ZeroMQ P2P transport
pip install -e ".[p2p]"

Symlink for spawned agents

Spawned agents run in fresh shells without pip's bin in PATH. Create a symlink:

mkdir -p ~/bin
ln -sf "$(which clawteam)" ~/bin/clawteam

# Add ~/bin to PATH if not already there (add to ~/.zshrc or ~/.bashrc)
export PATH="$HOME/bin:$PATH"

OpenClaw skill and exec approvals (OpenClaw users only)

# Install the ClawTeam skill so OpenClaw agents understand coordination commands
mkdir -p ~/.openclaw/workspace/skills/clawteam
cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md

# Allow spawned agents to run clawteam without interactive prompts
python3 -c "
import json, pathlib
p = pathlib.Path.home() / '.openclaw' / 'exec-approvals.json'
if p.exists():
    d = json.loads(p.read_text())
    d.setdefault('defaults', {})['security'] = 'allowlist'
    p.write_text(json.dumps(d, indent=2))
    print('Updated: security = allowlist')
else:
    print('Run openclaw once first, then re-run this step')
"
openclaw approvals allowlist add --agent "*" "*/clawteam"

Automated installer (Steps 2–5 in one shot)

git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
bash scripts/install-openclaw.sh

Verify

clawteam --version
clawteam config health        # All green = ready
openclaw skills list | grep clawteam  # OpenClaw users only

---

Core Concepts

Concept	What it is
Team	Named group of agents sharing a task board and inbox
Leader	The coordinating agent that spawns and monitors workers
Worker	A spawned agent with its own git worktree and tmux window
Worktree	Isolated git branch (clawteam/{team}/{agent}) — no merge conflicts
Task	Unit of work with status: pending → in_progress → completed / blocked
Inbox	Point-to-point or broadcast message queue between agents
Transport	File-based (default) or ZeroMQ P2P

---

Key CLI Commands

Team management

# Create a team (leader registers itself)
clawteam team spawn-team my-team \
  --description "Build the auth module" \
  --agent-name leader

# List all teams
clawteam team list

# Show team members and status
clawteam team show my-team

Spawning workers

# Spawn an OpenClaw worker (default)
clawteam spawn --team my-team \
  --agent-name alice \
  --task "Implement OAuth2 flow"

# Spawn with explicit agent type
clawteam spawn tmux openclaw --team my-team \
  --agent-name bob \
  --task "Write unit tests for auth"

# Spawn a Claude Code worker
clawteam spawn tmux claude --team my-team \
  --agent-name carol \
  --task "Set up CI pipeline"

# Spawn a Codex worker
clawteam spawn tmux codex --team my-team \
  --agent-name dave \
  --task "Optimize database queries"

# Subprocess backend (non-tmux, e.g. Cursor)
clawteam spawn subprocess cursor --team my-team \
  --agent-name eve \
  --task "Review and document APIs"

Task management

# List all tasks for a team
clawteam task list my-team

# List tasks owned by a specific agent
clawteam task list my-team --owner alice

# List tasks by status
clawteam task list my-team --status pending
clawteam task list my-team --status in_progress
clawteam task list my-team --status completed

# Create a task manually
clawteam task create my-team \
  --title "Implement login endpoint" \
  --description "POST /auth/login, returns JWT" \
  --owner alice

# Create a task with dependency (bob's task unblocks after alice completes hers)
clawteam task create my-team \
  --title "Write auth tests" \
  --owner bob \
  --blocked-by <alice-task-id>

# Update task status
clawteam task update my-team <task-id> --status completed

# Block until all tasks in a team are done (useful in scripts)
clawteam task wait my-team

Inter-agent messaging

# Send a message from leader to alice
clawteam inbox send my-team alice \
  "Please use the OpenAPI spec at docs/api.yaml for all endpoint contracts."

# Read your inbox (as the agent named 'alice')
clawteam inbox receive my-team alice

# Peek without consuming messages
clawteam inbox peek my-team alice

# Broadcast to all team members
clawteam inbox broadcast my-team \
  "API schema finalized. All teams unblocked."

Monitoring and dashboards

# Terminal kanban board (snapshot)
clawteam board show my-team

# Auto-refreshing live dashboard
clawteam board live my-team

# Tiled tmux view — all agent windows side by side
clawteam board attach my-team

# Web dashboard (real-time updates)
clawteam board serve --port 8080
clawteam board serve my-team --port 8080  # Filter to one team

Worktree and merge operations

# Checkpoint current worktree state (commit in worker branch)
clawteam worktree checkpoint my-team alice \
  --message "OAuth2 flow complete"

# Merge a worker's worktree back into main
clawteam worktree merge my-team alice --into main

# Merge all workers
clawteam worktree merge-all my-team --into main

# Clean up worktrees after merging
clawteam worktree cleanup my-team

Template-based launches

# Launch a predefined team from a TOML template
clawteam launch hedge-fund \
  --team fund1 \
  --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"

# List available templates
clawteam launch --list

---

Configuration

ClawTeam stores team state in .clawteam/ in your project root:

.clawteam/
  teams/
    my-team/
      manifest.json       # Team metadata and member list
      tasks.json          # Task board
      inbox/              # Per-agent message queues
        alice.jsonl
        bob.jsonl

Global config:

# Show current config
clawteam config show

# Run health check
clawteam config health

# Set default agent type
clawteam config set default_agent openclaw

# Set default transport (file or zmq)
clawteam config set transport file

---

Real Code Examples

Python: orchestrate a team programmatically

import subprocess
import json

def clawteam(*args) -> str:
    """Run a clawteam command and return stdout."""
    result = subprocess.run(
        ["clawteam", *args],
        capture_output=True, text=True, check=True
    )
    return result.stdout.strip()

# Create team
clawteam("team", "spawn-team", "myteam",
         "--description", "Build REST API",
         "--agent-name", "leader")

# Spawn workers
clawteam("spawn", "--team", "myteam",
         "--agent-name", "backend",
         "--task", "Implement CRUD endpoints for /users")

clawteam("spawn", "--team", "myteam",
         "--agent-name", "tester",
         "--task", "Write pytest suite for /users endpoints")

# Monitor until done
import time
while True:
    output = clawteam("task", "list", "myteam", "--status", "in_progress")
    remaining = [l for l in output.splitlines() if l.strip()]
    if not remaining:
        break
    print(f"Tasks in progress: {len(remaining)}")
    time.sleep(30)

# Merge all worktrees
clawteam("worktree", "merge-all", "myteam", "--into", "main")
clawteam("worktree", "cleanup", "myteam")
print("Done. All branches merged.")

Python: send a message and wait for reply

import subprocess, time, json

TEAM = "myteam"

def send(to: str, msg: str):
    subprocess.run(
        ["clawteam", "inbox", "send", TEAM, to, msg],
        check=True
    )

def receive(agent: str, timeout: int = 300) -> list[str]:
    """Poll inbox until a message arrives or timeout."""
    deadline = time.time() + timeout
    while time.time() < deadline:
        result = subprocess.run(
            ["clawteam", "inbox", "receive", TEAM, agent],
            capture_output=True, text=True
        )
        lines = [l for l in result.stdout.splitlines() if l.strip()]
        if lines:
            return lines
        time.sleep(5)
    raise TimeoutError(f"No message for {agent} within {timeout}s")

# Leader asks backend for API spec location
send("backend", "Where is the final OpenAPI spec? Reply with the file path.")
replies = receive("leader")
spec_path = replies[0]
print(f"Backend replied: {spec_path}")

TOML team template

Create templates/fullstack.toml:

[team]
name = "{team_name}"
description = "{goal}"

[[agents]]
name = "architect"
task = "Design system architecture and OpenAPI spec for: {goal}"
agent = "openclaw"

[[agents]]
name = "backend"
task = "Implement backend per architect's OpenAPI spec"
agent = "openclaw"
blocked_by = ["architect"]

[[agents]]
name = "frontend"
task = "Build React frontend consuming the backend API"
agent = "openclaw"
blocked_by = ["architect"]

[[agents]]
name = "tester"
task = "Write integration and unit tests covering backend and frontend"
agent = "openclaw"
blocked_by = ["backend", "frontend"]

[[agents]]
name = "devops"
task = "Set up CI/CD pipeline, Dockerfile, and deployment config"
agent = "openclaw"
blocked_by = ["backend"]

Launch it:

clawteam launch fullstack \
  --team myapp \
  --goal "Build a SaaS invoicing tool with Stripe integration"

Shell script: full pipeline

#!/usr/bin/env bash
set -euo pipefail

TEAM="research-$(date +%s)"
GOAL="${1:-Optimize the training loop in train.py}"

echo "==> Creating team: $TEAM"
clawteam team spawn-team "$TEAM" \
  --description "$GOAL" \
  --agent-name leader

echo "==> Spawning research agents"
for i in 1 2 3 4; do
  clawteam spawn --team "$TEAM" \
    --agent-name "researcher$i" \
    --task "Research direction $i for: $GOAL"
done

echo "==> Watching live dashboard (Ctrl-C to exit)"
clawteam board live "$TEAM" &
DASH_PID=$!

echo "==> Waiting for all tasks to complete"
clawteam task wait "$TEAM"
kill $DASH_PID 2>/dev/null || true

echo "==> Merging results"
clawteam worktree merge-all "$TEAM" --into main
clawteam worktree cleanup "$TEAM"

echo "==> Done. Check git log for merged branches."
git log --oneline -10

---

Common Patterns

Pattern 1: Dependency chain (sequential with parallelism)

# Step 1: architect works alone
clawteam spawn --team myteam --agent-name architect \
  --task "Design schema and API contracts"

# Step 2: backend + frontend unblock after architect
ARCH_TASK=$(clawteam task list myteam --owner architect --json | jq -r '.[0].id')

clawteam task create myteam \
  --title "Backend implementation" \
  --owner backend \
  --blocked-by "$ARCH_TASK"

clawteam task create myteam \
  --title "Frontend implementation" \
  --owner frontend \
  --blocked-by "$ARCH_TASK"

# Both backend and frontend agents spawn and self-block until architect finishes
clawteam spawn --team myteam --agent-name backend --task "See assigned task"
clawteam spawn --team myteam --agent-name frontend --task "See assigned task"

Pattern 2: Leader-worker with result aggregation

# Leader spawns workers, waits, then reads inbox for results
clawteam spawn --team myteam --agent-name worker1 --task "Analyze logs/server1.log"
clawteam spawn --team myteam --agent-name worker2 --task "Analyze logs/server2.log"

# Workers send results to leader when done:
# clawteam inbox send myteam leader "server1: 3 critical errors at 14:32, 15:01, 15:44"

# Leader polls inbox
clawteam inbox receive myteam leader

Pattern 3: Broadcast coordination

# Notify all agents of a shared context change
clawteam inbox broadcast myteam \
  "IMPORTANT: API base URL changed to https://api.example.com/v2. Update all clients."

Pattern 4: ZeroMQ P2P transport for low-latency teams

pip install -e ".[p2p]"
clawteam config set transport zmq

# All subsequent spawns use ZeroMQ instead of file-based queues
clawteam spawn --team myteam --agent-name worker1 --task "Low-latency task"

---

Troubleshooting

Problem	Cause	Fix
clawteam: command not found	pip bin not in PATH	ln -sf $(which clawteam) ~/bin/clawteam and add ~/bin to PATH
Spawned agents can't find clawteam	Fresh shell misses pip PATH	Verify ~/bin/clawteam symlink exists
Agents block on permission prompts	exec-approvals security is "full"	Run the exec approvals config step above
openclaw approvals fails	Gateway not running	Run openclaw gateway first, then retry
exec-approvals.json not found	OpenClaw never initialized	Run openclaw once, then retry the approvals step
pip install -e . fails	Missing build deps	pip install hatchling first
Tasks stuck in pending	Worker crashed or not spawned	clawteam board show <team> — check tmux windows
Merge conflicts on merge-all	Two workers edited same file	Resolve in each worktree branch before merging
Web dashboard not loading	Port in use	clawteam board serve --port 9090

Debugging a stuck team

# See all team members and their last-known status
clawteam team show myteam

# Check task board
clawteam task list myteam

# Attach to all agent windows in a tiled tmux view
clawteam board attach myteam

# Read any unread messages
clawteam inbox peek myteam leader
clawteam inbox peek myteam alice

Reset a team

# Clean up worktrees without merging (destructive)
clawteam worktree cleanup myteam --force

# Delete team state entirely
rm -rf .clawteam/teams/myteam

---

Supported Agents Reference

Agent	Spawn syntax	Notes
OpenClaw	clawteam spawn --team T --agent-name N	Default — no flag needed
Claude Code	clawteam spawn tmux claude --team T --agent-name N	Requires claude in PATH
Codex	clawteam spawn tmux codex --team T --agent-name N	Requires codex in PATH
nanobot	clawteam spawn tmux nanobot --team T --agent-name N	Requires nanobot in PATH
Cursor	clawteam spawn subprocess cursor --team T --agent-name N	Experimental
Custom script	clawteam spawn subprocess python myscript.py --team T --agent-name N	Any CLI agent

---

Resources

• Repo: https://github.com/win4r/ClawTeam-OpenClaw
• Upstream: https://github.com/HKUDS/ClawTeam
• OpenClaw: https://openclaw.ai
• Demo video: https://youtu.be/aZT9d8qrirY
• Autoresearch use case: https://github.com/novix-science/autoresearch