open-claw-team/.openclaw/workspace/skills/clawteam-multi-agent-coordination/SKILL.md

name, description, version

name	description	version
ClawTeam Multi-Agent Coordination	This skill should be used when the user asks to "create a team", "spawn agents", "assign tasks", "coordinate multiple agents", "check team status", "view kanban board", "send messages between agents", "manage team tasks", "monitor team progress", or mentions "clawteam", "multi-agent coordination", "team collaboration", "agent inbox", "task board", "spawn worker". This skill should also be triggered when the current task is complex enough to benefit from splitting into subtasks and delegating to multiple agents — for example when the user asks to "build a full-stack app", "refactor the entire codebase", "implement multiple features in parallel", or when the agent determines that the work scope exceeds what a single agent can efficiently handle alone. Provides comprehensive guidance for using the ClawTeam CLI to orchestrate multi-agent teams with task management, messaging, monitoring, runtime profiles, git context, and recovery tooling.	0.4.0

ClawTeam Multi-Agent Coordination

ClawTeam is a framework-agnostic CLI tool for coordinating multiple AI agents as a team. It provides team/task management, inter-agent messaging, git worktree isolation, provider-aware runtime profiles, git context injection, snapshots, and terminal-based monitoring dashboards.

All operations are performed via the oh CLI (shorthand for clawteam). Data is stored in ~/.clawteam/ by default.

Official repo: https://github.com/HKUDS/ClawTeam

Installation

pip install clawteam

Requires Python 3.10+. For P2P transport support: pip install clawteam[p2p].

Prerequisites

• tmux installed (default spawn backend)
• A CLI coding agent such as openclaw, claude, codex
• A git repository for worktree isolation and context features
• Default dependencies installed if you want the TUI wizard (oh profile wizard)

Core Concepts

Teams — Named groups of agents with one leader and zero or more workers.

Inbox — File-based message queue per agent. receive is destructive; peek is not.

Tasks — Shared task board with pending, in_progress, completed, and blocked. Tasks support dependency chains and priorities.

Profiles — Reusable client/provider/runtime configs used by spawn and launch.

Presets — Shared provider templates used to generate one or more profiles.

Context — Git/worktree-aware context tools for overlap checks, recent changes, and prompt injection.

Board — Team dashboard with kanban tasks, inbox counts, and message history views, plus gource activity visualization.

Quick Start

Set Up a Team with Tasks

export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"

oh team spawn-team my-team -d "Project team" -n leader
oh task create my-team "Design system" -o leader
oh task create my-team "Implement feature" -o worker1
oh task create my-team "Write tests" -o worker2
oh board show my-team

Configure Runtime Profiles

# Inspect built-in provider templates
oh preset list
oh preset show moonshot-cn

# Generate a reusable profile from a preset
oh preset generate-profile moonshot-cn claude --name claude-kimi

# Or use the interactive TUI
oh profile wizard

# Claude Code on a fresh machine/home may need onboarding repair once
oh profile doctor claude

# Smoke-test the profile before using it in a team
MOONSHOT_API_KEY=... oh profile test claude-kimi

Spawn and Coordinate Agents

⚠️ CRITICAL for OpenClaw environments: oh spawn defaults to claude as backend+command. ALWAYS explicitly specify tmux openclaw:

oh spawn tmux openclaw --team <team> --agent-name <name> --task "..."

# ✅ CORRECT for OpenClaw — ALWAYS use tmux openclaw
oh spawn tmux openclaw --team my-team --agent-name worker1 --task "Implement the auth module"
oh spawn tmux openclaw --team my-team --agent-name worker2 --task "Write unit tests"

# With non-default provider/model via profile
oh spawn tmux --profile claude-kimi --team my-team --agent-name worker5 --task "Build API endpoints"

# ❌ WRONG — will fail, defaults to claude
oh spawn --team my-team --agent-name worker1 --task "..."
oh spawn tmux claude --team my-team --agent-name worker1 --task "..."

oh board attach my-team
oh inbox send my-team worker1 "Start implementing the auth module"
oh board live my-team --interval 3

Spawn Defaults

Setting	Default	Override
Backend	tmux	oh spawn subprocess ...
Command	claude (default) / openclaw (ours)	oh spawn tmux openclaw for our setup
Workspace	auto (git worktree)	--no-workspace or config workspace=never
Permissions	skip	--no-skip-permissions or config skip_permissions=false
Runtime profile	none	--profile <name>

Important: For OpenClaw setups, use oh spawn tmux openclaw — NOT oh spawn (default=claude).

Use --profile whenever you need a non-default provider, model, endpoint, or auth mapping.

Task Lifecycle

# Create with dependencies
oh task create my-team "Deploy" --blocked-by <impl-task-id>,<test-task-id>

# Create with priority
oh task create my-team "Hotfix prod issue" --priority high

# Update status
oh task update my-team <task-id> --status in_progress
oh task update my-team <task-id> --status completed

# Filter tasks
oh task list my-team --status blocked
oh task list my-team --owner worker1
oh task list my-team --priority high

Waiting for Sub-Agents

oh task wait my-team
oh task wait my-team --timeout 300 --poll-interval 10
oh task wait my-team --agent coordinator
oh --json task wait my-team --timeout 600

Worker Loop Protocol

Workers should not stop after completing the initial --task. The expected loop is:

# 1. Check tasks assigned to you
oh task list my-team --owner worker1

# 2. Finish any pending work, then check for new instructions
oh inbox receive my-team --agent worker1

# 3. If idle, notify the leader and keep monitoring for follow-ups
oh lifecycle idle my-team

Repeat the loop until the leader explicitly shuts the worker down.

Git Context and Conflict Checks

oh context log my-team
oh context conflicts my-team
oh context inject my-team --agent worker1

Use these before reassigning work, continuing another worker's task, or merging overlapping changes.

Snapshots and Recovery

oh team snapshot my-team --tag before-refactor
oh team snapshots my-team
oh team restore my-team --snapshot before-refactor

Activity Visualization

oh board gource my-team --log-only
oh board gource my-team --live

Prefer --log-only in headless environments.

Supported CLI Agents

Common validated CLIs include:

• claude
• codex
• gemini
• kimi
• nanobot
• openclaw

OpenClaw worker spawns are normalized automatically. Bare openclaw commands are promoted to the agent entrypoint and wired with --local, --session-id, and --message as needed.

Configure non-default providers through profile + preset instead of hardcoding env vars into prompts.

Command Groups

Group	Purpose	Key Commands
preset	Shared provider templates	list, show, generate-profile, bootstrap
profile	Reusable client/provider configs	list, show, set, test, wizard, doctor
team	Team lifecycle	spawn-team, discover, status, request-join, approve-join, cleanup, snapshot, restore
inbox	Messaging	send, broadcast, receive, peek, watch
task	Task management	create, get, update, list, wait
board	Monitoring and visualization	show, overview, live, attach, serve, gource
context	Git/worktree context	diff, files, conflicts, log, inject
plan	Plan approval	submit, approve, reject
lifecycle	Agent lifecycle	request-shutdown, approve-shutdown, idle
spawn	Process spawning	spawn [backend] [command]
identity	Identity management	show, set

JSON Output

All commands support --json for machine-readable output. Put the flag before the subcommand:

oh --json team discover
oh --json board show my-team
oh --json task list my-team --status pending

Important Notes

• inbox receive consumes messages. Use inbox peek for non-destructive reads.
• Task status blocked is auto-set when --blocked-by is specified at creation.
• Completing a task auto-unblocks tasks that list it in blockedBy.
• Tasks also support priority; use high for urgent unblockers and production fixes.
• Workers are expected to keep polling tasks/inbox after the first task instead of exiting immediately.
• oh spawn defaults to tmux, git worktree isolation, and skip-permissions.
• oh launch also respects skip_permissions, so template workers no longer stall on approval prompts.
• All file writes use atomic tmp+rename to prevent corruption.
• Identity env vars are set automatically when spawning via oh spawn.
• Use board attach <team> to watch all agents in a tiled tmux layout.
• board show JSON and the browser board now include message history with member-aware aliases, which is useful for inbox triage and handoffs.
• Prefer --profile for non-default providers/models instead of manually exporting provider env vars.
• profile is the final runtime object; preset is a reusable template for generating profiles.
• For Claude Code on a fresh machine/home, run oh profile doctor claude once before spawning.
• context inject and context conflicts are the recommended way to hand off cross-worktree tasks safely.

Additional Resources

• references/cli-reference.md — Complete CLI reference with commands, options, and data models
• references/workflows.md — Multi-agent workflows: setup, spawn coordination, join protocol, plan approval, graceful shutdown, monitoring patterns