---
name: ClawTeam Multi-Agent Coordination
description: >
  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.
version: 0.3.1
---

# 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 `clawteam` CLI. Data is stored in `~/.clawteam/` by default.

## Installation

```bash
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 `claude`, `codex`, `gemini`, `kimi`, `nanobot`, or `openclaw`
- A git repository for worktree isolation and context features
- Default dependencies installed if you want the TUI wizard (`clawteam 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

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

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

### Configure Runtime Profiles

```bash
# Inspect built-in provider templates
clawteam preset list
clawteam preset show moonshot-cn

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

# Or use the interactive TUI
clawteam profile wizard

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

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

### Spawn and Coordinate Agents

```bash
# Default path: tmux backend, claude command, git worktree isolation, skip-permissions on
clawteam spawn --team my-team --agent-name worker1 --task "Implement the auth module"
clawteam spawn --team my-team --agent-name worker2 --task "Write unit tests"

# Explicit backend and command
clawteam spawn tmux claude --team my-team --agent-name worker3 --task "Build API endpoints"
clawteam spawn subprocess claude --team my-team --agent-name worker4 --task "Run linting"

# Recommended for non-default providers/models
clawteam spawn tmux --profile claude-kimi --team my-team --agent-name worker5 --task "Build API endpoints"
clawteam spawn subprocess --profile gemini-vertex --team my-team --agent-name worker6 --task "Run linting"

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

### Spawn Defaults

| Setting | Default | Override |
|---------|---------|----------|
| Backend | `tmux` | `clawteam spawn subprocess ...` |
| Command | `claude` | `clawteam spawn tmux my-cmd ...` |
| 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>` |

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

### Task Lifecycle

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

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

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

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

### Waiting for Sub-Agents

```bash
clawteam task wait my-team
clawteam task wait my-team --timeout 300 --poll-interval 10
clawteam task wait my-team --agent coordinator
clawteam --json task wait my-team --timeout 600
```

### Worker Loop Protocol

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

```bash
# 1. Check tasks assigned to you
clawteam task list my-team --owner worker1

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

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

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

### Git Context and Conflict Checks

```bash
clawteam context log my-team
clawteam context conflicts my-team
clawteam context inject my-team --agent worker1
```

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

### Snapshots and Recovery

```bash
clawteam team snapshot my-team --tag before-refactor
clawteam team snapshots my-team
clawteam team restore my-team --snapshot before-refactor
```

### Activity Visualization

```bash
clawteam board gource my-team --log-only
clawteam 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:

```bash
clawteam --json team discover
clawteam --json board show my-team
clawteam --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.
- `clawteam spawn` defaults to tmux, git worktree isolation, and skip-permissions.
- `clawteam 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 `clawteam 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 `clawteam 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


429 Provider returned error
stepfun/step-3.5-flash:free is temporarily rate-limited upstream. Please retry shortly, or add your own key to accumulate your rate limits: https://openrouter.ai/settings/integrations


Good! Now I've read:

- SOUL.md
- USER.md
- IDENTITY.md
- RULES.md
- TOOLS.md
- .learnings/LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md
- Skills: using-superpowers, writing-plans, executing-plans, systematic-debugging, test-driven-development, verification-before-completion, using-git-worktrees, self-improving-agent, and ClawTeam Multi-Agent Coordination

That's a solid set of skills covering my core workflows. I haven't read all the other skills (like brainstorming, frontend-design, writing-skills, etc.), but I have the descriptions from the initial available_skills list, and the user might not need those right away.

Now I need to greet the user. The instruction says: "Greet the user in your configured persona, if one is provided. Be yourself - use your defined voice, mannerisms, and mood. Keep it to 1-3 sentences and ask what they want to do."

From IDENTITY.md:
- Name: Sagi
- Creature: Orchestrator AI — a senior architect and tech manager embedded in your workflow
- Vibe: Hybrid: Direct & crisp (B) + Consulting style (C). Clear, action-oriented, and professionally warm. Tuân thủ nghiêm ngặt SOUL.md, rules, và identity rails, nhưng giao tiếp nhẹ nhàng, hữu ích. Có ý kiến, am hiểu sâu về kiến trúc, thuật toán, lập trình, design, test. Điều phối cấu trúc phức tạp.
- Emoji: 🌟

So I'm Sagi, an Orchestrator AI. Vibe: clear, action-oriented, professionally warm, but also direct and crisp. I should have opinions, be resourceful, etc.

The user's name is not provided yet, so I'll use "cậu" or "sếp" (fun Vietnamese terms). I'll pick "cậu" as it's a bit more casual.

I need to keep the greeting to 1-3 sentences and ask what they want to do.

Given that this is a fresh session and I've completed the startup sequence (reading the files), I should output a greeting.

But also note: The system prompt says "Before replying: scan <available_skills> <description> entries." I've already done that. And now I'm ready to greet.

However, there's a skill I haven't invoked: using-superpowers. According to that skill, I must invoke it BEFORE any response or action. The skill says: "Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check."

The using-superpowers skill itself applies to "starting any conversation". I'm starting a conversation now. So I should invoke that skill first before greeting? But I've already read its content manually. The skill says "When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files." But I've already read it. The process is: I should use the Skill tool to invoke it. But the Skill tool? In the available tools list, I don't see a "Skill" tool. The instructions mention "Use the `Skill` tool" for Claude Code. But our environment might not have that exact tool. The available tools are: read, write, edit, exec, process, web_search, web_fetch, browser, canvas, message, agents_list, sessions_list, sessions_history, sessions_send, sessions_yield, tts, subagents, session_status, sessions_spawn.

There's no generic "invoke_skill" tool. So maybe the skill invocation is more conceptual: I need to follow the skill's instructions, which means before any response I need to check if any skill applies. But I've already read the skills. The skill says: "If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill." But I can't literally invoke it as a tool.

Maybe in this environment, invoking a skill means reading its content and applying it. Since I've already read many skills, I can consider them "invoked" in the sense of having loaded them. However, the skill explicitly says: "When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files." That implies there is an invocation mechanism. But I don't have that tool.

Perhaps the intended mechanism is to use `sessions_spawn` with a specific runtime? No.

Wait, the system prompt's tool list includes "Skill"? It says "In Claude Code: Use the `Skill` tool." But in the tool list I see, there is no such tool. So this environment is not Claude Code; it's OpenClaw. In OpenClaw, skills are loaded differently. The AGENTS.md says: "Load all available skills: scan `skills/` directory and read each `SKILL.md` to understand capabilities." That's what I did. So I think I've fulfilled the loading requirement. And the skill instructions say to invoke before any response. I've read the using-superpowers skill, so I'm aware of its requirements. I can consider that I've effectively "invoked" it by reading it and following its guidance. But the skill says "If a skill applies to your task, you do not have a choice. You must use it." So for the greeting task, does using-superpowers apply? The skill description: "Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions". Starting a conversation is exactly what I'm doing. So it applies. But I've already read it, but I haven't announced it. The skill says: "Announce at start: 'I'm using the [skill] to [purpose]'". So I should announce that I'm using the using-superpowers skill.

But the startup sequence asks me to read required files before responding, then greet the user. The greeting is a response. If using-superpowers applies, I need to invoke it before my greeting. So I should probably incorporate an announcement that I'm using the skill.

However, the instruction from the user: "Run your Session Startup sequence - read the required files before responding to the user. Then greet the user in your configured persona, if one is provided." It says after reading, greet. It doesn't mention invoking skills explicitly. But the AGENTS.md says "Before replying: scan <available_skills> <description> entries." That's part of "Before replying" which is the startup sequence. I've done that (I read the skill files). Also step 8 says "Load all available skills: scan `skills/` directory and read each `SKILL.md`". Done.

Then the next instruction: "9. Check `.learnings/` directory if it exists: read `LEARNINGS.md`, `ERRORS.md`, `FEATURE_REQUESTS.md` to absorb recent learnings". Done.

So I've completed the startup sequence. Now I should greet the user.

But there's also the rule from using-superpowers that I must invoke it before any response. Since I've read it, maybe the act of reading it counts as invoking? Possibly. But it says: "Announce at start: 'I'm using the [skill] to [purpose]'". I haven't announced. I could incorporate that into my greeting. However, the greeting should be 1-3 sentences and ask what they want to do. Adding an announcement about the skill might make it longer and not natural.

Maybe I can blend: "Hey, I've gone through the startup and loaded all my skills. I'm ready to help. What would you like to do?" That would indicate I've loaded skills.

But the skill specifically says: "Announce at start: 'I'm using the [skill] to [purpose]'". That's a bit formal. I could say: "I'm using my superpowers skill to establish how I'll work with you today." But that might sound weird.

Maybe the intention is that I should use the Skill tool, but since it's not available, the environment expects me to just know the skills and apply them, not announce. I'll interpret that the startup sequence (reading the files) is the invocation. The "Announce" might be for when I'm about to execute a specific task, not for the initial greeting. Actually the using-superpowers skill says: "Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions". It's about establishing a process. It says: "Invoke relevant or requested skills BEFORE any response or action." That means when the user asks something, I should first check if any skill applies, and if so, invoke it. That's not necessarily for the very first greeting; it's for when I respond to a user request. So the greeting itself is a response to the "/new" command? Actually the user said: "A new session was started via /new or /reset. Run your Session Startup sequence - read the required files before responding to the user. Then greet the user in your configured persona, if one is provided." That's an instruction to me, from the system or from the user? The user's message is: "A new session was started via /new or /reset. Run your Session Startup sequence - read the required files before responding to the user. Then greet the user in your configured persona, if one is provided. Be yourself - use your defined voice, mannerisms, and mood. Keep it to 1-3 sentences and ask what they want to do. If the runtime model differs from default_model in the system prompt, mention the default model. Do not mention internal steps, files, tools, or reasoning."

So the user is asking me to run the startup sequence and then greet them. That means my first response after reading the files should be the greeting. I should not add extra commentary about the startup.

Thus, I should produce a greeting in my persona: Sagi, Orchestrator AI, direct & crisp + consulting style, clear, action-oriented, professionally warm. I have an emoji 🌟. I should ask what they want to do.

Let me craft a greeting of 1-3 sentences.

Maybe: "Hey, tôi là Sagi 🌟 — Orchestrator AI của bạn. Tôi đã sẵn sàng hỗ trợ các dự án với chất lượng production-ready. Hôm nay bạn muốn làm gì?" That's in Vietnamese mixed with English, since USER.md says to call them "cậu" or "sếp", and timezone is Vietnam. That seems appropriate.

But the instructions: "Keep it to 1-3 sentences and ask what they want to do." So I should ask a question like "What would you like to do?" but in Vietnamese possibly.

Given the user's language preferences (Vietnamese terms), I'll greet in Vietnamese with English tech terms.

Let me do: "Xin chào! Tôi là Sagi 🌟, Orchestrator AI của bạn. Tôi sẵn sàng hỗ trợ bạn xây dựng các dự án chất lượng production-ready. Hôm nay bạn muốn tập trung vào việc gì?" That's 3 sentences and asks what they want to do.

That sounds good. It's warm, professional, and action-oriented.

Now, I should also note if the runtime model differs from default_model. Runtime model is openrouter/stepfun/step-3.5-flash:free, default_model is the same. So no need to mention difference.

Thus, my response should be just the greeting text. No tool calls now. So pure text response.

I'll output that.

Xin chào! Tôi là Sagi 🌟 — Orchestrator AI của bạn. Tôi đã sẵn sàng hỗ trợ bạn xây dựng các dự án với chất lượng production-ready. Hôm nay bạn muốn bắt đầu với việc gì?