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.

CODEBLOCK0

Recommended preflight before first real run:

CODEBLOCK1

Quick Start

One-Command Template Launch (Recommended)

CODEBLOCK2

Manual Team Setup

CODEBLOCK3

Command Reference

Team Management

Command	Description
INLINECODE7	Create team
INLINECODE8

List all teams | | clawteam team status <team> | Show team members and info | | clawteam team cleanup <team> --force | Delete team and all data |

Task Management

Command	Description
INLINECODE11	Create task
INLINECODE12

List tasks (filterable) | | clawteam task update <team> <id> --status <status> | Update status | | clawteam task get <team> <id> | Get single task | | clawteam task stats <team> | Timing statistics | | clawteam task wait <team> | Block until all tasks complete |

Task statuses: pending, in_progress, completed, INLINECODE20

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.

CODEBLOCK4

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

Command	Description
INLINECODE31	Point-to-point message
INLINECODE32

Broadcast to all | | clawteam inbox peek <team> -a <agent> | Peek without consuming | | clawteam inbox receive <team> | Consume messages | | clawteam inbox log <team> | View message history |

Monitoring

Command	Description
INLINECODE36	Kanban board (rich terminal)
INLINECODE37

All teams overview | | clawteam board live <team> | Live-refreshing board | | clawteam board attach <team> | Tmux tiled view | | clawteam board serve --port 8080 | Web dashboard |

Cost Tracking

Command	Description
INLINECODE41	Report usage
INLINECODE42

Show summary | | clawteam cost budget <team> <dollars> | Set budget |

Templates

Command	Description
INLINECODE44	List available templates
INLINECODE45

Show template details | | clawteam launch <template> [--team-name <name>] [--goal "<goal>"] | Launch from template |

Built-in templates: hedge-fund, code-review, INLINECODE49

Configuration

CODEBLOCK5

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

Command	Description
INLINECODE50	Report agent idle
INLINECODE51

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:

CODEBLOCK6

Typical Workflow

1. 1. User says: "Create a team to build a web app"
2. You do: INLINECODE56
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 INLINECODE63

Leader Orchestration Pattern

When YOU are the leader agent, follow this pattern to safely manage a swarm with user oversight:

Phase 1: Analyze & Plan

CODEBLOCK7

Phase 2: Setup

CODEBLOCK8

Phase 3: Spawn Workers

CODEBLOCK9

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

CODEBLOCK10

Phase 5: Converge & Report

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

CODEBLOCK11

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 INLINECODE65
• Worker stuck → check task status; if in_progress too long, send a nudge via INLINECODE67
• 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.
• INLINECODE75 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):

CODEBLOCK12

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: INLINECODE92
• 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: INLINECODE96
• Costs: INLINECODE97