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:

clawteam --version

If the command is missing, install it and continue:

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

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

# 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

# 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

# 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

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:

# 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

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

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

Activity Visualization

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:

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

ClawTeam CLI Complete Reference

Global Options

clawteam [--version] [--json] [--data-dir PATH] <command>

• --json — Output JSON instead of human-readable text. Apply before subcommand: clawteam --json team discover
• --data-dir PATH — Override data directory (default: ~/.clawteam)

Environment Variables

ClawTeam agents use these environment variables for identity:

When spawning agents via clawteam spawn, these are set automatically. Legacy OH_* aliases remain accepted for compatibility.

---

Team Commands (clawteam team)

team spawn-team

Create a new team and register the leader.

clawteam team spawn-team <name> [options]

Example:

clawteam team spawn-team dev-team -d "Backend development team" -n alice

team discover

List all existing teams.

clawteam team discover
clawteam --json team discover

Returns: name, description, leadAgentId, memberCount for each team.

team status

Show team configuration and member list.

clawteam team status <team>

team request-join

Request to join a team. Blocks until leader approves/rejects or timeout.

clawteam team request-join <team> <proposed-name> [options]

team approve-join

Approve a pending join request (leader only).

clawteam team approve-join <team> <request-id> [--assigned-name NAME]

team reject-join

Reject a pending join request (leader only).

clawteam team reject-join <team> <request-id> [--reason TEXT]

team cleanup

Delete a team and all its data (config, inboxes, tasks).

clawteam team cleanup <team> [--force]

---

Inbox Commands (clawteam inbox)

inbox send

Send a point-to-point message to an agent.

clawteam inbox send <team> <to> <content> [options]

inbox broadcast

Broadcast a message to all team members (except sender).

clawteam inbox broadcast <team> <content> [options]

inbox receive

Receive and consume messages from inbox (destructive — messages are deleted).

clawteam inbox receive <team> [options]

inbox peek

Peek at messages without consuming them (non-destructive).

clawteam inbox peek <team> [--agent NAME]

inbox watch

Watch inbox for new messages in real-time (blocking, Ctrl+C to stop).

clawteam inbox watch <team> [--agent NAME] [--poll-interval 1.0]

---

Task Commands (clawteam task)

task create

Create a new task.

clawteam task create <team> <subject> [options]

Example:

clawteam task create dev-team "Implement auth" -o alice -d "Add JWT authentication"

task get

Get a single task by ID.

clawteam task get <team> <task-id>

task update

Update a task's status, owner, or dependencies.

clawteam task update <team> <task-id> [options]

When a task is marked completed, any tasks blocked by it are automatically unblocked (moved from blocked to pending if no other blockers remain).

task list

List all tasks for a team, with optional filters.

clawteam task list <team> [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]

---

Board Commands (clawteam board)

board show

Show detailed team board data. Human output renders the kanban board; JSON output also includes members with inbox identity fields plus persistent message history from the event log.

clawteam board show <team>
clawteam --json board show <team>

Recent board payloads include member-aware message aliases such as memberKey, inboxName, fromLabel, and toLabel, which are used by the browser board to filter inbox history.

board overview

Show summary of all teams in a table.

clawteam board overview
clawteam --json board overview

board live

Live-refreshing kanban board. Auto-refreshes at interval. Ctrl+C to stop.

clawteam board live <team> [--interval 2.0]

---

Plan Commands (clawteam plan)

plan submit

Submit a plan for leader approval. Content can be inline text or a file path.

clawteam plan submit <team> <agent> <plan-content-or-file> [--summary TEXT]

plan approve

Approve a submitted plan.

clawteam plan approve <team> <plan-id> <agent> [--feedback TEXT]

plan reject

Reject a submitted plan.

clawteam plan reject <team> <plan-id> <agent> [--feedback TEXT]

---

Lifecycle Commands (clawteam lifecycle)

lifecycle request-shutdown

Request an agent to shut down.

clawteam lifecycle request-shutdown <team> <from-agent> <to-agent> [--reason TEXT]

lifecycle approve-shutdown

Agent agrees to shut down.

clawteam lifecycle approve-shutdown <team> <request-id> <agent>

lifecycle reject-shutdown

Agent rejects shutdown request.

clawteam lifecycle reject-shutdown <team> <request-id> <agent> [--reason TEXT]

lifecycle idle

Send idle notification to leader (agent has no more work).

clawteam lifecycle idle <team> [--last-task ID] [--task-status STATUS]

---

Spawn Command

Spawn a new agent process with team environment variables.

clawteam spawn <backend> <command...> [options]

Backends: subprocess, tmux

Example:

clawteam spawn subprocess claude --team dev-team --agent-name bob --agent-type researcher

---

Identity Commands (clawteam identity)

identity show

Show current agent identity from environment variables.

clawteam identity show

identity set

Print shell export commands to set identity environment variables.

eval $(clawteam identity set --agent-name alice --team dev-team)

---

Data Model

Task Statuses

Message Types

File Storage Layout

~/.clawteam/
├── teams/{team}/
│   ├── config.json          # TeamConfig (name, members, leader)
│   └── inboxes/{agent}/     # msg-{timestamp}-{uuid}.json files
├── tasks/{team}/
│   └── task-{id}.json       # Individual task files
└── plans/
    └── {agent}-{id}.md      # Plan documents

ClawTeam Coordination Workflows

Workflow 1: Create a Team and Assign Tasks

A common workflow for setting up a new project team.

# 1. Set leader identity
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"

# 2. Create team
clawteam team spawn-team my-project -d "Web app development" -n leader

# 3. Create tasks with dependencies
clawteam task create my-project "Design API schema" -o leader
# => Task ID: aaa11111

clawteam task create my-project "Implement backend" -o backend-dev --blocked-by aaa11111
# => Task ID: bbb22222 (auto-set to blocked status)

clawteam task create my-project "Build frontend" -o frontend-dev --blocked-by aaa11111
# => Task ID: ccc33333

clawteam task create my-project "Integration testing" --blocked-by bbb22222,ccc33333
# => Task ID: ddd44444

# 4. Check board
clawteam board show my-project

# 5. As tasks complete, update status (auto-unblocks dependents)
clawteam task update my-project aaa11111 --status completed
# bbb22222 and ccc33333 auto-unblock from blocked -> pending

Workflow 2: Multi-Agent Spawn and Coordination

Full lifecycle of spawning multiple agents and coordinating work.

# Leader creates team
clawteam team spawn-team dev-team -d "Feature development" -n leader

# Spawn worker agents (each gets identity env vars automatically)
clawteam spawn tmux claude --team dev-team --agent-name researcher --agent-type researcher
clawteam spawn tmux claude --team dev-team --agent-name coder --agent-type general-purpose

# Leader creates tasks
clawteam task create dev-team "Research best practices" -o researcher
clawteam task create dev-team "Implement solution" -o coder

# Leader sends instructions via inbox
clawteam inbox send dev-team researcher "Research authentication patterns for microservices"
clawteam inbox send dev-team coder "Wait for researcher's findings before starting implementation"

# Monitor progress
clawteam board live dev-team --interval 5

Worker Agent Perspective

From inside a spawned worker agent:

# Identity is pre-set via environment
clawteam identity show
# => agentName: researcher, teamName: dev-team

# Check inbox for instructions
clawteam inbox receive dev-team

# Do work, then update task
clawteam task update dev-team <task-id> --status in_progress
# ... work ...
clawteam task update dev-team <task-id> --status completed

# Notify leader when idle
clawteam lifecycle idle dev-team --last-task <task-id> --task-status completed

Workflow 3: Join Request Protocol

When an agent wants to join an existing team dynamically.

# Agent side: request to join (blocks until response)
clawteam team request-join dev-team bob --capabilities "frontend specialist" --timeout 120

# Leader side: check inbox for join requests
clawteam inbox peek dev-team --agent leader
# => join_request from bob, requestId: join-abc123

# Leader approves
clawteam team approve-join dev-team join-abc123

# Agent receives approval with assigned name and agent ID
# => Approved! Joined as 'bob' (agentId: xyz789)

Workflow 4: Plan Approval Flow

For teams requiring plan review before execution.

# Worker submits plan
clawteam plan submit dev-team coder "1. Refactor auth module\n2. Add OAuth2\n3. Update tests" \
  --summary "Auth system modernization"

# Leader reviews (checks inbox)
clawteam inbox receive dev-team --agent leader
# => plan_approval_request with planId

# Leader approves or rejects
clawteam plan approve dev-team <plan-id> coder --feedback "Looks good, proceed"
# or
clawteam plan reject dev-team <plan-id> coder --feedback "Add error handling section"

Workflow 5: Graceful Shutdown

Coordinated shutdown of team agents.

# Leader requests shutdown of a worker
clawteam lifecycle request-shutdown dev-team leader coder --reason "All tasks complete"

# Worker checks inbox, sees shutdown request
clawteam inbox receive dev-team --agent coder
# => shutdown_request, requestId: shut-xyz

# Worker finishes current work, then approves
clawteam lifecycle approve-shutdown dev-team shut-xyz coder

# Leader cleans up team when all agents are done
clawteam team cleanup dev-team --force

Workflow 6: Monitoring and Debugging

Using board and inbox commands to monitor team health.

# Quick overview of all teams
clawteam board overview

# Detailed view of one team
clawteam board show dev-team

# JSON output for scripting/parsing
clawteam --json board show dev-team | jq '.taskSummary'
clawteam --json task list dev-team --status blocked | jq '.[].subject'

# Check who has unread messages
clawteam --json board show dev-team | jq '.members[] | select(.inboxCount > 0) | .name'

# Live monitoring
clawteam board live dev-team --interval 3

# Watch a specific agent's inbox
clawteam inbox watch dev-team --agent leader

Common Patterns

Task with Dependencies

# Create a chain: A -> B -> C
clawteam task create team "Task A" -o alice
# ID: aaa
clawteam task create team "Task B" -o bob --blocked-by aaa
# ID: bbb (status: blocked)
clawteam task create team "Task C" -o carol --blocked-by bbb
# ID: ccc (status: blocked)

# When A completes, B auto-unblocks
clawteam task update team aaa --status completed
# B moves from blocked -> pending

# When B completes, C auto-unblocks
clawteam task update team bbb --status completed

Broadcasting Updates

# Leader broadcasts to all team members
clawteam inbox broadcast dev-team "Sprint planning at 2pm. Check your tasks."

# Broadcast with routing key for filtering
clawteam inbox broadcast dev-team "Build passed" --key "ci-notification"

Using JSON Output in Scripts

# Get all blocked tasks
BLOCKED=$(clawteam --json task list dev-team --status blocked)
echo "$BLOCKED" | jq -r '.[].id'

# Count pending messages per team
clawteam --json board overview | jq '.[] | "\(.name): \(.pendingMessages) pending"'

# Get team member names
clawteam --json team status dev-team | jq -r '.members[].name'