clawteam-openclaw-swarm

What this skill does

```markdown
---
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:

```bash
# macOS
brew install [email protected] 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.

```bash
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:

```bash
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)

```bash
# 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)

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

### Verify

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

```bash
# 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

```python
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", "