Multi-agent swarm coordination via the ClawTeam CLI. Use when the user wants to create agent teams, spawn multiple agents to work in parallel, coordinate tasks with dependencies, broadcast messages between agents, monitor progress via kanban board, or launch pre-built team templates (hedge-fund, code-review, research-paper). ClawTeam uses git worktree isolation + tmux + filesystem-based messaging. Trigger phrases: team, swarm, multi-agent, clawteam, spawn agents, parallel agents, agent team.
Instrucciones de origen · Vista previa de solo lectura
name
clawteam
description
Multi-agent swarm coordination via the ClawTeam CLI. Use when the user wants to create agent teams, spawn multiple agents to work in parallel, coordinate tasks with dependencies, broadcast messages between agents, monitor progress via kanban board, or launch pre-built team templates (hedge-fund, code-review, research-paper). ClawTeam uses git worktree isolation + tmux + filesystem-based messaging. Trigger phrases: team, swarm, multi-agent, clawteam, spawn agents, parallel agents, agent team.
ClawTeam — Multi-Agent Swarm Coordination
Overview
ClawTeam is a CLI tool (clawteam) for orchestrating multiple AI agents as self-organizing swarms. It uses git worktree isolation, tmux windows, and filesystem-based messaging. OpenClaw is the default agent backend.
CLI binary: clawteam (installed via pip, available in PATH)
Quick Start
One-Command Template Launch (Recommended)
# Launch a pre-built team from a template
clawteam launch hedge-fund --team fund1
clawteam launch code-review --team review1
clawteam launch research-paper --team paper1
Dependency auto-resolution: When a blocking task completes, dependent tasks automatically change from blocked to pending.
Task locking: When a task moves to in_progress, it is locked by the calling agent. Other agents cannot claim it unless they use --force. Stale locks from dead agents are automatically released.
Agent Spawning
IMPORTANT: Always use the default command (openclaw) — do NOT override to claude or other agents. The default handles permissions, prompt injection, and nesting detection correctly. If you specify claude as the command, agents will get stuck on interactive permission prompts.
clawteam config show # Show all settings
clawteam config set transport file # Set transport backend
clawteam config set skip_permissions true# Auto-skip permission prompts
clawteam config health # System health check
Other Commands
Command
Description
clawteam lifecycle idle <team> --agent <name>
Report agent idle
clawteam session save <team> --session-id <id>
Save session for resume
clawteam plan submit <team> "<plan>" --from <agent>
Submit plan for approval (team-scoped storage)
clawteam workspace list <team>
List git worktrees
clawteam workspace merge <team> --agent <name>
Merge agent branch
JSON Output
Add --json before any subcommand for machine-readable output:
clawteam --json task list my-team
clawteam --json team status my-team
Typical Workflow
User says: "Create a team to build a web app"
You do: clawteam team spawn-team webapp -d "Build web app" -n leader
Create tasks: Use clawteam task create with --blocked-by for dependencies
Spawn agents: Use clawteam spawn for each worker
Monitor: Start a background polling loop immediately — do NOT wait for user to ask
Communicate: Use clawteam inbox broadcast for team-wide updates
Deliver: Proactively send final results to the user as soon as all tasks complete
Cleanup: clawteam cost show, clawteam task stats, merge worktrees, then clawteam team cleanup webapp --force
Leader Orchestration Pattern
When YOU are the leader agent, follow this pattern to autonomously manage a swarm:
Phase 1: Analyze & Plan
1. Understand the user's goal
2. Break it into independent subtasks
3. Identify dependencies between tasks (what must finish before what)
4. Decide how many worker agents are needed
Phase 2: Setup
# Create team
clawteam team spawn-team <team> -d "<goal description>" -n leader
# Create tasks with dependency chains
clawteam task create <team> "Design API" -o architect
# Save the returned task ID (e.g., abc123)
clawteam task create <team> "Build backend" -o backend --blocked-by abc123
clawteam task create <team> "Build frontend" -o frontend --blocked-by abc123
clawteam task create <team> "Integration tests" -o tester --blocked-by <backend-id>,<frontend-id>
Phase 3: Spawn Workers
# Each spawn launches an openclaw tui in its own tmux window
clawteam spawn -t <team> -n architect --task "Design REST API schema for <goal>"
clawteam spawn -t <team> -n backend --task "Implement backend based on API schema"
clawteam spawn -t <team> -n frontend --task "Build React frontend"
clawteam spawn -t <team> -n tester --task "Write and run integration tests"
Phase 4: Monitor Loop
IMPORTANT: Start monitoring immediately after spawning — do NOT wait for the user to ask for status updates. Run the monitor loop in the background right away so you can:
Push mid-progress updates proactively — when ~50% of tasks complete, send the user a brief status update (e.g. "4/7 agents done, 3 still working"). Do NOT wait for them to ask.
Deliver final results immediately when all tasks complete.
# Poll task status every 30-60 secondswhiletrue; do
clawteam --json task list <team> | python3 -c "
import sys, json
tasks = json.load(sys.stdin)
done = sum(1 for t in tasks if t['status'] == 'completed')
total = len(tasks)
print(f'{done}/{total} complete')
if done == total: print('ALL DONE'); sys.exit(0)
"# Check for messages from workers
clawteam inbox receive <team>
# IMPORTANT: Send a mid-progress update to the user when roughly half the tasks are donesleep 30
done
Phase 5: Converge & Report
IMPORTANT: Proactively deliver results to the user as soon as all tasks complete. Do NOT wait for the user to ask. Include the final output, a summary, and cost/timing stats. ALWAYS merge worktrees and clean up.
# After all tasks complete — do ALL of these steps:
clawteam board show <team> # Final status
clawteam cost show <team> # Total cost — include in report to user
clawteam task stats <team> # Timing stats — include in report to user# Merge each worker's branch back to mainfor agent in <agent1> <agent2> ...; do
clawteam workspace merge <team> --agent $agentdone
clawteam team cleanup <team> --force # Clean up — ALWAYS do this last# Then: send the final deliverables to the user immediately
Decision Rules for the Leader
Independent tasks → spawn workers in parallel
Sequential tasks → use --blocked-by to chain them; ClawTeam auto-unblocks
Worker asks for help → check inbox, provide guidance via inbox send
Worker stuck → check task status; if in_progress too long, send a nudge via inbox send
Worker done → verify result via inbox message, then move to next phase
All done → merge worktrees, deliver results to user proactively, then cleanup
Always → start background monitoring immediately after spawn; never wait for user to ask for status
Data Location
All state stored in ~/.clawteam/:
Teams: ~/.clawteam/teams/<team>/config.json
Tasks: ~/.clawteam/tasks/<team>/task-<id>.json (with fcntl file locking for concurrent safety)
Plans: ~/.clawteam/plans/<team>/<agent>-<plan_id>.md (team-scoped, isolated per team)