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. Source: https://github.com/win4r/ClawTeam-OpenClaw

Optimization Notes#

This skill is based on the upstream ClawTeam project and includes additional safety/approval optimizations for real-world operations:

• Channel-aware approval UX:
  • Feishu uses interactive approval cards with same-row Approve/Reject buttons.
  • Telegram uses inline keyboard approval buttons.
  • Other channels fall back to explicit text approval ( approve / reject).
• Safer execution defaults:
  • No permission-bypass guidance.
  • No infinite unattended monitor loops.
  • Destructive operations require explicit approval checkpoints.

These changes are intentional enhancements, not a verbatim copy.

CLI binary: clawteam (must be preinstalled and available in PATH)

Install & Verification#

This skill is instruction-only. It does not install clawteam automatically.

Install from a trusted source and pin a version/tag when possible.

bash

# Example only: verify upstream release/tag before install
pipx install "git+https://github.com/win4r/ClawTeam-OpenClaw.git@<trusted-tag>"

# Verify binary and version
which clawteam
clawteam --version

Recommended preflight before first real run:

bash

# Use a disposable repo/worktree first
clawteam config health
clawteam team spawn-team dry-run -d "safety check" -n leader
clawteam team cleanup dry-run --force

Quick Start#

One-Command Template Launch (Recommended)#

bash

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

bash

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

CommandDescriptionclawteam team spawn-team <name> -d "<desc>" -n <leader>Create teamclawteam team discoverList all teamsclawteam team status <team>Show team members and infoclawteam team cleanup <team> --forceDelete team and all data

Task Management#

CommandDescriptionclawteam task create <team> "<subject>" -o <owner> [-d "<desc>"] [--blocked-by <id>]Create taskclawteam task list <team> [--owner <name>]List tasks (filterable)clawteam task update <team> <id> --status <status>Update statusclawteam task get <team> <id>Get single taskclawteam task stats <team>Timing statisticsclawteam task wait <team>Block until all tasks complete

Task statuses: pending, in_progress, completed, blocked

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#

Use the default command ( openclaw) unless the user explicitly requests another backend. Keep normal permission and trust prompts enabled.

bash

# 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

High-impact note: spawn subprocess and custom backend modes can execute arbitrary code through delegated commands. Use only in trusted repositories/environments.

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
• Workspace trust and permission prompts must be reviewed and confirmed by the user or operator

Messaging#

CommandDescriptionclawteam inbox send <team> <to> "<msg>" --from <sender>Point-to-point messageclawteam inbox broadcast <team> "<msg>" --from <sender>Broadcast to allclawteam inbox peek <team> -a <agent>Peek without consumingclawteam inbox receive <team>Consume messagesclawteam inbox log <team>View message history

Monitoring#

CommandDescriptionclawteam board show <team>Kanban board (rich terminal)clawteam board overviewAll teams overviewclawteam board live <team>Live-refreshing boardclawteam board attach <team>Tmux tiled viewclawteam board serve --port 8080Web dashboard

Cost Tracking#

CommandDescriptionclawteam cost report <team> --input-tokens <N> --output-tokens <N> --cost-cents <N>Report usageclawteam cost show <team>Show summaryclawteam cost budget <team> <dollars>Set budget

Templates#

CommandDescriptionclawteam template listList available templatesclawteam template show <name>Show template detailsclawteam launch <template> [--team-name <name>] [--goal "<goal>"]Launch from template

Built-in templates: hedge-fund, code-review, research-paper

Configuration#

bash

clawteam config show                           # Show all settings
clawteam config set transport file             # Set transport backend
clawteam config health                         # System health check

Do not enable permission-skipping settings in shared or production environments. Keep permission prompts enabled for auditability.

Credentials & Channel Integration#

This skill itself does not directly read or manage Feishu/Telegram tokens. Channel credentials are managed by the OpenClaw channel plugins/runtime.

• Feishu interactive approvals require a configured Feishu channel account in OpenClaw.
• Telegram interactive approvals require a configured Telegram bot/channel account in OpenClaw.
• Never paste bot tokens, app secrets, or webhook secrets into team tasks, git worktrees, or chat messages.

Other Commands#

CommandDescriptionclawteam lifecycle idle <team> --agent <name>Report agent idleclawteam session save <team> --session-id <id>Save session for resumeclawteam plan submit <team> "<plan>" --from <agent>Submit plan for approval (team-scoped storage)clawteam workspace list <team>List git worktreesclawteam workspace merge <team> --agent <name>Merge agent branch

JSON Output#

Add --json before any subcommand for machine-readable output:

bash

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: Use bounded polling with timeout/attempt limits
6. Communicate: Use clawteam inbox broadcast for team-wide updates
7. Deliver: Share progress and ask for confirmation before destructive actions
8. Cleanup: After confirmation, run 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 safely manage a swarm with user oversight:

Phase 1: Analyze & Plan#

text

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#

bash

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

bash

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

Use a bounded monitor loop (for example, max 40 iterations with 30s interval = 20 minutes), then stop and report status.

1. Push mid-progress updates — when ~50% of tasks complete, send the user a brief status update (e.g. "4/7 agents done, 3 still working").
2. Deliver final results when all tasks complete.
3. Escalate to user if timeout is reached, instead of running indefinitely.

bash

# Poll task status every 30-60 seconds with an upper bound
max_rounds=40
for ((round=1; round<=max_rounds; round++)); 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>
  # Send a mid-progress update when roughly half the tasks are done
  sleep 30
done

# Timeout branch: ask user whether to continue monitoring
echo "Monitor timeout reached; request user confirmation to continue."

Phase 5: Converge & Report#

Before merge/cleanup, ask for user confirmation. Include the final output, a summary, and cost/timing stats.

bash

# 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
# Ask user for confirmation before merge and cleanup
# Merge each worker's branch back to main (after confirmation)
for agent in <agent1> <agent2> ...; do
  clawteam workspace merge <team> --agent $agent
done
clawteam team cleanup <team> --force  # Clean up after confirmation
# Then: send the final deliverables to the user

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 → confirm with user, then merge worktrees and cleanup
• Always → prefer bounded monitoring and explicit user checkpoints for long-running actions

Safety Guardrails#

• Never bypass security, trust, or permission prompts.
• Never run infinite unattended loops; use bounded retries/timeouts.
• Ask for user confirmation before destructive actions (force cleanup, branch merge, mass task updates).
• If a command requests elevated privileges or modifies sensitive paths, pause and ask first.
• Keep an audit trail by reporting what was executed and why.
• Treat these as high-impact operations and confirm intent before running: spawn subprocess, workspace merge, team cleanup --force, board serve.

Remote Approval Cards#

Render approval UI based on the current message source (channel-aware behavior):

• feishu source: always use Feishu interactive card ( schema: "2.0") with approval_decision button callback.
• telegram source: use inline keyboard buttons ( Approve / Reject) with callback payload carrying approval_id and decision.
• Other sources (cli/web/unknown): use a text approval prompt and require explicit reply approve or reject.
• Required fields for all channels:
  • approval_id (unique, one-time)
  • action (what will be executed)
  • risk_level (low/medium/high)
  • scope (files/commands/resources affected)
  • deadline (approval timeout)

Feishu template (same-row buttons, recommended):

json

{
  "schema": "2.0",
  "config": { "wide_screen_mode": true },
  "header": {
    "title": { "tag": "plain_text", "content": "Remote Approval" },
    "template": "orange"
  },
  "body": {
    "elements": [
      {
        "tag": "markdown",
        "content": "**approval_id**: `<id>`\n**action**: <action>\n**risk_level**: <level>\n**scope**: <scope>\n**deadline**: <time>"
      },
      { "tag": "hr" },
      {
        "tag": "column_set",
        "flex_mode": "none",
        "horizontal_align": "left",
        "columns": [
          {
            "tag": "column",
            "width": "auto",
            "elements": [
              {
                "tag": "button",
                "text": { "tag": "plain_text", "content": "Approve" },
                "type": "primary",
                "value": { "action": "approval_decision", "approval_id": "<id>", "decision": "approve" }
              }
            ]
          },
          {
            "tag": "column",
            "width": "auto",
            "elements": [
              {
                "tag": "button",
                "text": { "tag": "plain_text", "content": "Reject" },
                "type": "default",
                "value": { "action": "approval_decision", "approval_id": "<id>", "decision": "reject" }
              }
            ]
          }
        ]
      }
    ]
  }
}

Source detection hint:

• Prefer runtime channel metadata (for example, channel=feishu or channel=telegram).
• If unavailable, infer from session key patterns:
  • agent:*:feishu:* -> Feishu mode
  • agent:*:telegram:* -> Telegram mode

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>/