ClawTeam — Multi-Agent Swarm Coordination

Overview

ClawTeam is a CLI tool (

clawteam

CLI binary:

clawteam

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

Manual Team Setup

# 1. Create team with leader
clawteam team spawn-team my-team -d "Build a web app" -n leader

# 2. Create tasks with dependencies
clawteam task create my-team "Design API schema" -o architect
# Returns task ID, e.g., abc123

clawteam task create my-team "Implement auth" -o backend --blocked-by abc123
clawteam task create my-team "Build frontend" -o frontend --blocked-by abc123
clawteam task create my-team "Write tests" -o tester

# 3. Spawn agents (each gets its own tmux window + git worktree)
clawteam spawn -t my-team -n architect --task "Design the API schema for a web app"
clawteam spawn -t my-team -n backend --task "Implement OAuth2 authentication"
clawteam spawn -t my-team -n frontend --task "Build React dashboard"

# 4. Monitor
clawteam board show my-team        # Kanban view
clawteam board attach my-team      # Tmux tiled view (all agents side-by-side)
clawteam board serve --port 8080   # Web dashboard

Command Reference

Team Management

clawteam team spawn-team <name> -d "<desc>" -n <leader>

clawteam team discover

clawteam team status <team>

clawteam team cleanup <team> --force

Task Management

clawteam task create <team> "<subject>" -o <owner> [-d "<desc>"] [--blocked-by <id>]

clawteam task list <team> [--owner <name>]

clawteam task update <team> <id> --status <status>

clawteam task get <team> <id>

clawteam task stats <team>

clawteam task wait <team>

Task statuses:

pending

in_progress

completed

blocked

Dependency auto-resolution: When a blocking task completes, dependent tasks automatically change from

blocked

pending

Task locking: When a task moves to

in_progress

--force

Agent Spawning

IMPORTANT: Always use the default command (

openclaw

claude

claude

# Default (RECOMMENDED): spawns openclaw tui in tmux with prompt
clawteam spawn -t <team> -n <name> --task "<task description>"

# Explicit backend (still uses openclaw by default)
clawteam spawn tmux -t <team> -n <name> --task "<task>"
clawteam spawn subprocess -t <team> -n <name> --task "<task>"

# With git worktree isolation
clawteam spawn -t <team> -n <name> --task "<task>" --workspace --repo /path/to/repo

Each spawned agent gets:

• Its own tmux window (visible via

  board attach

  )
• Its own git worktree branch (

  clawteam/{team}/{agent}

  )
• An auto-injected coordination prompt (how to use clawteam CLI)
• Environment variables:

  CLAWTEAM_AGENT_NAME

  ,

  CLAWTEAM_TEAM_NAME

  , etc.

Spawn safety features:

• Commands are pre-validated before launch — you get a clear error if the agent CLI is not installed
• If a spawn fails, the registered team member and worktree are automatically rolled back
• Claude Code and Codex workspace trust prompts are auto-confirmed in fresh worktrees

Messaging

clawteam inbox send <team> <to> "<msg>" --from <sender>

clawteam inbox broadcast <team> "<msg>" --from <sender>

clawteam inbox peek <team> -a <agent>

clawteam inbox receive <team>

clawteam inbox log <team>

Monitoring

clawteam board show <team>

clawteam board overview

clawteam board live <team>

clawteam board attach <team>

clawteam board serve --port 8080

Cost Tracking

clawteam cost report <team> --input-tokens <N> --output-tokens <N> --cost-cents <N>

clawteam cost show <team>

clawteam cost budget <team> <dollars>

Templates

clawteam template list

clawteam template show <name>

clawteam launch <template> [--team-name <name>] [--goal "<goal>"]

Built-in templates:

hedge-fund

code-review

research-paper

Configuration

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

clawteam lifecycle idle <team> --agent <name>

clawteam session save <team> --session-id <id>

clawteam plan submit <team> "<plan>" --from <agent>

clawteam workspace list <team>

clawteam workspace merge <team> --agent <name>

JSON Output

Add

--json

clawteam --json task list my-team
clawteam --json team status my-team

Typical Workflow

1. User says: "Create a team to build a web app"
2. You do:

   clawteam team spawn-team webapp -d "Build web app" -n leader

3. Create tasks: Use

   clawteam task create

   with

   --blocked-by

   for dependencies
4. Spawn agents: Use

   clawteam spawn

   for each worker
5. Monitor: Start a background polling loop immediately — do NOT wait for user to ask
6. Communicate: Use

   clawteam inbox broadcast

   for team-wide updates
7. Deliver: Proactively send final results to the user as soon as all tasks complete
8. 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:

1. 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.
2. Deliver final results immediately when all tasks complete.

# Poll task status every 30-60 seconds
while true; 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 done
  sleep 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 main
for agent in <agent1> <agent2> ...; do
  clawteam workspace merge <team> --agent $agent
done
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)
• Messages:

  ~/.clawteam/teams/<team>/inboxes/<agent>/msg-*.json

• Costs:

  ~/.clawteam/costs/<team>/