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:

bashCopy code
clawteam --version

If the command is missing, install it and continue:

bashCopy code
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

bashCopy code
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

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

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

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

Task Lifecycle

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

bashCopy code
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:

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

bashCopy code
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

bashCopy code
clawteam team snapshot my-team --tag before-refactor
clawteam team snapshots my-team
clawteam team restore my-team --snapshot before-refactor

Activity Visualization

bashCopy code
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

JSON Output

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

bashCopy code
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