# ClawTeam

> Orchestrates multi-agent teams using the ClawTeam CLI, enabling task management, inter-agent messaging, git context integration, runtime profiles, and monitoring dashboards.

- Skill: `gabrielmoreira/clawteam` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/clawteam`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/clawteam/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs, AI & ML, Agent Building
- Tags: Clawteam, Cli Agent, Git Worktree, Kanban, Multi Agent, Task Board, Tmux
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/gabrielmoreira/clawteam

---


# 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

Check whether `clawteam` is already available:

```bash
clawteam --version
```

If the command is missing, install it and continue:

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