🇺🇸English

ClawTeam Multi-Agent Coordination

ClawTeam is a framework-agnostic CLI tool for coordinating multiple AI agents as a team. It provides file-based team management, inter-agent messaging, shared task tracking with dependency resolution, plan approval workflows, and terminal-based monitoring dashboards.

All operations are performed via the clawteam CLI. Data is stored in ~/.clawteam/ by default.

Installation

pip install clawteam

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

Prerequisites

• tmux installed (used by default spawn backend)
• A CLI coding agent (e.g. claude, codex, or any command-line agent)
• A git repository (for worktree isolation)

Core Concepts

Teams — A named group of agents with one leader and zero or more workers. Created via clawteam team spawn-team. The leader approves joins, reviews plans, and coordinates shutdown.

Inbox — File-based message queue per agent. inbox send for point-to-point, inbox broadcast for all members. inbox receive consumes messages (destructive); inbox peek reads without consuming.

Tasks — Shared task board with statuses: pending, in_progress, completed, blocked. Tasks support dependency chains (--blocks, --blocked-by). Completing a task auto-unblocks dependents.

Board — Terminal kanban dashboard. board show for single team, board overview for all teams, board live for real-time auto-refresh, board attach for tiled tmux view of all agents.

Identity — Each agent has env vars (CLAWTEAM_AGENT_ID, CLAWTEAM_AGENT_NAME, CLAWTEAM_AGENT_TYPE, CLAWTEAM_TEAM_NAME). Set automatically when spawned via clawteam spawn.

Quick Start

Set Up a Team with Tasks

# Set identity for the current session
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"

# Create team
clawteam team spawn-team my-team -d "Project team" -n leader

# Create tasks
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

# View board
clawteam board show my-team

Spawn and Coordinate Agents

# Spawn workers — defaults: 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"

# Or explicitly specify backend and command (positional args: [BACKEND] [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"

# Watch all agents working simultaneously (tiled tmux panes)
clawteam board attach my-team

# Send instructions
clawteam inbox send my-team worker1 "Start implementing the auth module"

# Monitor task board
clawteam board live my-team --interval 3

Spawn Defaults

Spawning agents uses sensible defaults — no flags needed for the common case:

Agents spawned with defaults get:

• Their own git worktree (isolated branch, no conflicts with other agents)
• Full tool permissions (--dangerously-skip-permissions) so they can work autonomously
• A tmux window you can watch with board attach

Task Lifecycle

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

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

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

Waiting for Sub-Agents

# Block until all tasks complete (no timeout)
clawteam task wait my-team

# With timeout and custom poll interval
clawteam task wait my-team --timeout 300 --poll-interval 10

# Monitor a specific agent's inbox instead of the leader
clawteam task wait my-team --agent coordinator

# JSON streaming output (NDJSON: progress + message events, then final result)
clawteam --json task wait my-team --timeout 600

Watching Agents Work

# Tile all agent tmux windows into one view (best way to observe)
clawteam board attach my-team

# Or attach to the tmux session manually and switch windows with Ctrl-b + number
tmux attach -t clawteam-my-team

Command Groups

JSON Output

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

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

Combine with jq for scripting:

clawteam --json board show my-team | jq '.taskSummary'
clawteam --json task list my-team | jq '.[].subject'

Important Notes

• inbox receive consumes messages (deletes files). 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 any tasks that list it in blockedBy.
• clawteam spawn defaults to tmux backend with git worktree isolation and skip-permissions.
• All file writes use atomic tmp+rename to prevent data 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.

Additional Resources

Reference Files

For detailed command arguments, data models, and storage layout:

• references/cli-reference.md — Complete CLI reference with all commands, options, and data models

For step-by-step coordination workflows and common patterns:

• references/workflows.md — Multi-agent workflows: team setup, spawn coordination, join protocol, plan approval, graceful shutdown, monitoring patterns

Weekly Installs

–

Repository

win4r/clawteam-openclaw

GitHub Stars

825

First Seen

–

Security Audits

Gen Agent Trust HubFailSocketPassSnykPass