Related Pages

Related topics: System Architecture, Quick Start Guide

Introduction to ClawTeam

ClawTeam is an agent swarm orchestration CLI designed to coordinate multiple coding agents—including Claude Code, Codex, OpenClaw, nanobot, and other terminal-native clients—from a single command-line interface. It serves as the coordination layer that enables agents to plan, delegate, and ship code together as a unified team.

Purpose and Scope

ClawTeam addresses a fundamental limitation in modern AI-assisted development: isolated agent sessions working independently without coordination. The platform provides:

• Team Management: Create and manage teams of agents with designated leaders
• Task Coordination: Shared task boards with dependency tracking and priority levels
• Inter-Agent Communication: File-based inbox system for point-to-point and broadcast messaging
• Session Management: Spawn, monitor, and lifecycle control of agent processes
• Context Injection: Git-aware context tools for worktree isolation and overlap detection

Sources: skills/clawteam/SKILL.md

Architecture Overview

ClawTeam follows a leader-worker architecture where one agent serves as the coordinator while others perform specialized tasks.

graph TD
    A[Leader Agent] --> B[Worker Agent 1]
    A --> C[Worker Agent 2]
    A --> D[Worker Agent N]
    B --> E[Task Store]
    C --> E
    D --> E
    A --> F[Message Inboxes]
    B --> F
    C --> F
    D --> F
    G[CLI Interface] --> A
    G --> H[Board Dashboard]

Core Components

Sources: clawteam/team/tasks.py:1-12

Data Storage Model

All data is persisted in ~/.clawteam/ with a structured directory 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

Sources: skills/clawteam/references/cli-reference.md

Task Management System

Tasks form the backbone of team coordination, supporting four distinct statuses:

Task Dependencies

Tasks support dependency chains through two parameters:

• --blocks: Task IDs this task blocks upon completion
• --blocked-by: Task IDs blocking this task from starting

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

Sources: skills/clawteam/references/cli-reference.md

graph LR
    T1[Task 1: Design] --> T2[Task 2: Implement]
    T2 --> T3[Task 3: Test]
    T3 --> T4[Task 4: Deploy]
    T1 -->|blocks| T2
    T2 -->|blocks| T3
    T3 -->|blocks| T4

Message Types

The inbox system supports various message types for inter-agent communication:

Sources: skills/clawteam/references/cli-reference.md

Spawn Backends

ClawTeam supports multiple spawn backends for launching agents:

The spawn command configures team environment variables for spawned agents:

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

Sources: clawteam/spawn/wsh_backend.py:1-30

Session Management

For Claude Code specifically, ClawTeam integrates with existing sessions:

# Session capture flow from clawteam/spawn/session_locators/claude.py
session_id = str(uuid.uuid4())
return PreparedSession(
    command=[*command, "--session-id", session_id],
    client=self.client,
    session_id=session_id,
    source="generated",
    confidence="exact",
    cwd=context.cwd,
)

The system can detect existing sessions via:

• Environment variables (CLAUDE_CODE_SESSION, CLAUDE_SESSION_ID)
• Project directory session files (.jsonl format)

Sources: clawteam/spawn/session_locators/claude.py:1-60

Lifecycle Management

Agents support a complete lifecycle for graceful shutdown:

graph TD
    A[Agent Running] --> B{Shutdown Request}
    B -->|approve| C[Agent Shuts Down]
    B -->|reject| D[Agent Continues]
    A --> E[Idle Notification]
    E --> F[Leader Reassigns Tasks]

Lifecycle Commands

Sources: skills/clawteam/references/cli-reference.md

Quick Start

Installation

clawteam --version  # Check if installed
pip install clawteam  # Requires Python 3.10+

Create and Manage a Team

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

# Spawn a team with leader
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 team board
clawteam board show my-team

Spawn Worker Agents

clawteam spawn tmux claude-code --team my-team --agent-name builder
clawteam spawn tmux claude-code --team my-team --agent-name reviewer

Sources: skills/clawteam/SKILL.md

Board Dashboard

The board command provides team visibility through multiple views:

# JSON output for integration
clawteam --json board show my-team

# Live monitoring
clawteam board live my-team --interval 2.0

Sources: skills/clawteam/references/cli-reference.md

Identity System

Each agent requires environment variables for identification within the team:

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

The identity system exposes:

• CLAWTEAM_AGENT_ID: Unique identifier
• CLAWTEAM_AGENT_NAME: Human-readable name
• CLAWTEAM_AGENT_TYPE: Role classification (leader, general-purpose, etc.)

Sources: clawteam/harness/context_recovery.py:1-40

Context Recovery

The harness system provides role-based context recovery for agents:

# Layer 5: One-liner teammate summaries from context_recovery.py
def _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:
    from clawteam.team.tasks import TaskStore
    store = TaskStore(team_name)
    tasks = store.list_tasks()
    # Group by owner, exclude self
    owner_status: dict[str, tuple[int, int]] = {}

This enables leaders to understand team workload distribution and assign tasks appropriately.

Sources: clawteam/harness/context_recovery.py:40-70

See Also

• CLI Reference - Complete command documentation
• SKILL.md - Comprehensive usage guide

Related Pages

Related topics: Introduction to ClawTeam, Agent Spawning System

Quick Start Guide

ClawTeam is an agent swarm orchestration CLI that enables coordination of multiple coding agents (Claude Code, Codex, OpenClaw, nanobot, and any terminal-native client) from a single command-line interface. This guide walks you through installation, team creation, agent spawning, and basic coordination workflows.

Prerequisites

Before getting started with ClawTeam, ensure your environment meets the following requirements:

Sources: skills/clawteam/SKILL.md:20-30

Installation

Standard Installation

Install ClawTeam via pip:

pip install clawteam

Installation with P2P Transport Support

For peer-to-peer transport capabilities:

pip install "clawteam[p2p]"

Verify Installation

Confirm ClawTeam is installed correctly:

clawteam --version

Sources: skills/clawteam/SKILL.md:12-18

Core Concepts

Understanding these fundamental concepts is essential before creating your first agent team.

Teams

Teams are named groups of agents with one designated leader and zero or more worker agents. The leader coordinates task distribution and monitors team progress. Sources: skills/clawteam/SKILL.md:32

Tasks

Shared task board with status tracking:

• pending — Not yet started
• in_progress — Currently being worked on
• completed — Done; auto-unblocks dependent tasks
• blocked — Waiting on other tasks to complete

Tasks support dependency chains and priority levels (low, medium, high, urgent). Sources: skills/clawteam/references/cli-reference.md:80-88

Inbox

File-based message queue per agent. Messages can be destructive (receive) or non-destructive (peek). Sources: skills/clawteam/SKILL.md:34

Spawn Backends

ClawTeam supports multiple agent spawning backends:

Sources: clawteam/spawn/wsh_backend.py:1-50

Step 1: Create a Team

Spawn a New Team

Create a team with a leader agent:

clawteam team spawn-team <team-name> [options]

Example:

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

The team leader will automatically be registered in the system. Sources: skills/clawteam/references/cli-reference.md:100-115

Verify Team Creation

Check team status and members:

clawteam team status <team-name>

List Existing Teams

Discover all teams in the network:

clawteam team discover

Or get JSON output for scripting:

clawteam --json team discover

Returns: name, description, leadAgentId, memberCount for each team. Sources: skills/clawteam/references/cli-reference.md:116-120

Step 2: Spawn Agents

Spawn an Agent into a Team

Add a worker agent to your team:

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

Example:

clawteam spawn tmux claude --team dev-sprint --agent-name builder --agent-type researcher

This spawns Claude Code in a tmux session named builder and registers it with the dev-sprint team. Sources: skills/clawteam/references/cli-reference.md:35-45

Agent Identity Setup

For spawned agents to operate within the team context, set identity environment variables:

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

View current agent identity:

clawteam identity show

Sources: skills/clawteam/references/cli-reference.md:46-55

Step 3: Manage Tasks

Create a Task

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

Example:

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

Update Task Status

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). Sources: skills/clawteam/references/cli-reference.md:60-80

List Team Tasks

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

Team Workflow Example

graph TD
    A[Install ClawTeam] --> B[Spawn Team with Leader]
    B --> C[Leader Creates Initial Tasks]
    C --> D[Spawn Worker Agents]
    D --> E[Workers Pick Tasks]
    E --> F[Complete Task]
    F --> G{Tasks Blocked?}
    G -->|Yes| H[Wait for Blockers]
    G -->|No| I[Mark Complete]
    H --> I
    I --> J{More Tasks?}
    J -->|Yes| E
    J -->|No| K[Idle Notification]

Terminal Workflow Demo

The following demonstrates the typical CLI workflow:

$ clawteam team spawn-team docs-sprint
✓ Team "docs-sprint" created

$ clawteam spawn tmux claude-code --agent-name builder
✓ Agent "builder" spawned in tmux

$ clawteam team status docs-sprint
docs-sprint  3 agents active
● T-001 Build landing page  done
● T-002 Write API docs  active
○ T-003 Review & merge  blocked

Sources: website/src/App.jsx:1-60

Lifecycle Management

Request Agent Shutdown

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

Approve/Reject Shutdown

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

Send Idle Notification

When an agent has no more work:

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

This notifies the team leader that the agent is available for new tasks. Sources: skills/clawteam/references/cli-reference.md:130-150

Communication Between Agents

Message Types

Send a Message

clawteam message send <team> <to-agent> <content>

Join a Team

Request to join an existing team:

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

The leader can approve or reject the request:

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

Sources: skills/clawteam/references/cli-reference.md:25-30

Plan Submission and Approval

Submit a Plan

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

Approve/Reject a Plan

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

Sources: skills/clawteam/references/cli-reference.md:95-108

Session Persistence

ClawTeam handles session persistence for agents like Claude Code. When spawning an agent:

1. If --continue or -c flag is used, the agent continues from its last session
2. Otherwise, a new session ID is generated automatically
3. Session state is captured and stored for future restoration

# Session capture flow
if prepared.session_id:
    return CapturedSession(
        session_id=prepared.session_id,
        client=self.client,
        source=prepared.source or "prepared",
        confidence=prepared.confidence or "exact",
        cwd=context.cwd,
    )
return self.current_session(context)

Sources: clawteam/spawn/session_locators/claude.py:30-45

Data Storage

All team data is stored in ~/.clawteam/ by default:

Task operations are backed by FileTaskStore:

from clawteam.store.base import BaseTaskStore, TaskLockError
from clawteam.store.file import FileTaskStore

TaskStore = FileTaskStore

Sources: clawteam/team/tasks.py:1-20

Next Steps

• Review the CLI Reference for complete command documentation
• Explore Git-aware execution features for repository integration
• Configure runtime profiles for different agent environments

Related Pages

Related topics: Introduction to ClawTeam, Transport Layer, Event System

System Architecture

Overview

ClawTeam is an agent swarm orchestration CLI that coordinates multiple coding agents (Claude Code, Codex, OpenClaw, nanobot, and any terminal-native client) from a single command-line interface. The system provides shared task graphs, persistent coordination, and git-aware execution across distributed agent workers.

The architecture follows a modular design with clear separation between spawning backends, team management, task storage, event handling, and transport layers. All data persists in ~/.clawteam/ by default, with support for P2P transport when agents operate on different machines.

Sources: skills/clawteam/SKILL.md:1-15

High-Level Component Architecture

graph TD
    subgraph "CLI Layer"
        CLI[clawteam CLI]
    end
    
    subgraph "Core Services"
        TM[Team Manager]
        TS[Task Store]
        EB[Event Bus]
        TR[Transport Layer]
    end
    
    subgraph "Spawn Backends"
        TMUX[Tmux Backend]
        WSH[Wsh Backend]
        SUB[Subprocess Backend]
    end
    
    subgraph "Agent Runtime"
        AG1[Agent 1]
        AG2[Agent 2]
        AGn[Agent N]
    end
    
    subgraph "Data Storage"
        ST[Store - FileSystem]
        IN[Inbox - per-agent]
        TK[Tasks JSON]
        PL[Plan Files]
    end
    
    CLI --> TM
    CLI --> TS
    CLI --> EB
    CLI --> TR
    TM --> TS
    TM --> EB
    EB --> TR
    TR --> AG1
    TR --> AG2
    AG1 --> ST
    AG2 --> ST
    ST --> IN
    ST --> TK
    ST --> PL

Core Modules

Task Store Layer

The task storage system provides a persistent, file-based task management interface. The TaskStore class serves as the primary abstraction, with implementations supporting different storage backends.

classDiagram
    class BaseTaskStore {
        <<abstract>>
        +create_task(task) Task
        +get_task(task_id) Task
        +update_task(task_id, updates) Task
        +list_tasks() List~Task~
        +delete_task(task_id)
        +acquire_lock(task_id) ContextManager
        +release_lock(task_id)
    }
    
    class FileTaskStore {
        +_base_path: Path
        +create_task(task) Task
        +get_task(task_id) Task
        +update_task(task_id, updates) Task
        +list_tasks() List~Task~
    }
    
    class TaskLockError {
        +Exception
    }
    
    BaseTaskStore <|-- FileTaskStore
    BaseTaskStore -- TaskLockError

Task Data Model

Sources: clawteam/team/tasks.py:1-15

Task Status Transitions

Sources: skills/clawteam/references/cli-reference.md:85-100

Event Bus

The event system enables inter-agent communication through a pub-sub pattern. Events flow through the transport layer to reach individual agent inboxes.

graph LR
    A[Agent A] -->|publish| EB[Event Bus]
    EB -->|deliver| IN1[Inbox A]
    EB -->|deliver| IN2[Inbox B]
    EB -->|deliver| INn[Inbox N]
    
    subgraph "Message Types"
        MSG[message]
        BC[broadcast]
        JR[join_request]
        PA[plan_approval_request]
        SR[shutdown_request]
        IDL[idle]
    end
    
    EB -.->|routes| MSG
    EB -.->|routes| BC
    EB -.->|routes| JR
    EB -.->|routes| PA
    EB -.->|routes| SR
    EB -.->|routes| IDL

Supported Message Types

Sources: skills/clawteam/references/cli-reference.md:110-125

Spawn Backend System

The spawn system launches agent processes using configurable backends. Each backend implements a common interface for process management and runtime injection.

Backend Architecture

graph TD
    subgraph "Spawn Factory"
        SF[Backend Factory]
    end
    
    SF --> TMUX[Tmux Backend]
    SF --> WSH[Wsh Backend]
    SF --> SUB[Subprocess Backend]
    
    subgraph "Agent Lifecycle"
        LAUNCH[Launch]
        MONITOR[Monitor]
        INJECT[Inject Runtime]
        TERMINATE[Terminate]
    end
    
    TMUX --> LAUNCH
    WSH --> LAUNCH
    SUB --> LAUNCH
    TMUX --> MONITOR
    WSH --> MONITOR
    SUB --> MONITOR
    WSH --> INJECT
    TMUX --> INJECT
    SUB --> INJECT

Spawn Command Parameters

Example Usage

clawteam spawn tmux claude --team dev-team --agent-name builder --agent-type researcher

Sources: skills/clawteam/references/cli-reference.md:25-45

Wsh Backend Implementation

The WebSocket-based spawn backend (wsh_backend.py) provides runtime message injection into running agent sessions.

def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
    """Best-effort runtime injection into a running wsh block."""
    from clawteam.spawn.registry import get_registry

    info = get_registry(team).get(agent_name, {})
    block_id = info.get("block_id", "") or self._blocks.get(agent_name, "")
    if not block_id:
        return False, f"wsh block for '{team}/{agent_name}' not found"
    if not _is_block_alive(block_id):
        return False, f"wsh block '{block_id}' is not alive"
    # ... RPC client payload delivery

Agent Registration Flow

1. Agent spawns with team_name, agent_name, backend type
2. Backend calls register_agent() with metadata
3. Spawn data persisted via persist_spawned_session()
4. Agent entry stored in registry for runtime lookups

Sources: clawteam/spawn/wsh_backend.py:1-55

Data Storage Layout

All persistent data resides under ~/.clawteam/ with a structured directory hierarchy:

~/.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

Inbox Operations

Team Structure

graph TD
    subgraph "Team: dev-team"
        L[Leader Agent]
        W1[Worker: alice]
        W2[Worker: bob]
        W3[Worker: charlie]
        
        L -->|manages| W1
        L -->|manages| W2
        L -->|manages| W3
        
        subgraph "Shared Resources"
            TB[Task Board]
            CH[Inbox Channel]
            CT[Context]
        end
        
        W1 --> TB
        W2 --> TB
        W3 --> TB
        W1 --> CH
        W2 --> CH
        W3 --> CH
    end

Team Commands

Sources: skills/clawteam/references/cli-reference.md:130-160

Context and Recovery System

The context recovery module provides role-specific context injection for agents operating within the harness system.

Role-Based Context Layers

def _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:
    """Layer 5: One-liner teammate summaries."""
    try:
        from clawteam.team.tasks import TaskStore
        store = TaskStore(team_name)
        tasks = store.list_tasks()

        # Group by owner, exclude self
        owner_status: dict[str, tuple[int, int]] = {}
        for t in tasks:
            if t.owner and t.owner != agent_name:
                done, total = owner_status.get(t.owner, (0, 0))
                total += 1
                if t.status == TaskStatus.COMPLETED:
                    done += 1
                owner_status[t.owner] = (done, total)
    except Exception:
        pass

Sources: clawteam/harness/context_recovery.py:1-75

Frontend Architecture

The website provides a browser-based dashboard for visualizing team state.

graph LR
    subgraph "React Components"
        App[App.jsx]
        TM[TerminalMockup]
        HG[HalfGlobe]
    end
    
    subgraph "UI Sections"
        H[Hero]
        F[Features]
        W[Workflow]
        D[Docs]
    end
    
    subgraph "Data Display"
        TL[Terminal Output]
        KB[Kanban Board]
        ST[Status Grid]
    end
    
    App --> TM
    App --> HG
    TM --> TL
    H --> KB
    F --> ST
    W --> D

Terminal Mockup Features

• Real-time team status display
• Agent spawn simulation
• Task progress visualization with status badges
• Animated cursor for active states

Sources: website/src/App.jsx:1-100

Communication Flow

sequenceDiagram
    participant L as Leader
    participant W1 as Worker Alice
    participant W2 as Worker Bob
    participant T as TaskStore
    participant I as Inbox
    
    W1->>L: request-join(team, "alice")
    L->>T: create_task()
    L->>W1: join_approved
    W1->>T: update_task(status=in_progress)
    W1->>L: plan_approval_request
    L->>W1: plan_approved
    W1->>T: update_task(status=completed)
    T->>W2: unblock(task_id)
    W2->>L: idle(last_task=T-001)

Key Dependencies

Sources: skills/clawteam/SKILL.md:1-40

Summary

ClawTeam's architecture centers on three pillars:

1. Team Coordination - Leader-based hierarchy with worker registration and task distribution
2. Persistent Storage - File-based task boards, inboxes, and plans under ~/.clawteam/
3. Flexible Spawning - Pluggable backends (tmux, subprocess, wsh) for agent lifecycle management

The system is designed for git-aware, multi-agent development workflows where agents share task context, communicate via typed messages, and maintain independent worktree isolation.

Related Pages

Related topics: System Architecture, Team Management

Event System

⚠️ Documentation Notice: This page documents the Event System based on available repository context. The core event system source files (clawteam/events/*.py) were not available in the retrieved context. This page derives event system behavior from CLI reference documentation and related modules.

Overview

The Event System in ClawTeam provides the inter-agent communication backbone that enables coordination between multiple autonomous agents in a team. Rather than exposing a standalone event bus API, ClawTeam integrates event-driven communication through its messaging infrastructure, task lifecycle hooks, and board system.

Sources: skills/clawteam/references/cli-reference.md

Message Types

The system defines several message/event types that flow between team members. These types represent the different categories of communication that agents use to coordinate.

Sources: skills/clawteam/references/cli-reference.md

Task Status Events

Task state transitions trigger automatic event behavior. When a task status changes, the system automatically propagates effects to dependent tasks.

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

Sources: skills/clawteam/references/cli-reference.md

Inter-Agent Communication Flow

graph TD
    A[Agent] -->|message| B[Team Inbox]
    A -->|broadcast| C[All Members]
    A -->|join_request| D[Leader]
    D -->|join_approved| A
    A -->|plan_approval_request| D
    D -->|plan_approved<br>plan_rejected| A
    A -->|shutdown_request| E[Target Agent]
    E -->|shutdown_approved<br>shutdown_rejected| A
    A -->|idle| D

Board and Inbox Architecture

The board system serves as the persistent event store, maintaining message history and team state.

~/.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

Sources: skills/clawteam/references/cli-reference.md

Board Show Command

The board show command displays team board data with member-aware message aliases:

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

Recent board payloads include:

• memberKey — identifies team member
• inboxName — target inbox identifier
• fromLabel / toLabel — message source and destination

These fields are used by the browser board to filter inbox history.

Sources: skills/clawteam/references/cli-reference.md

Lifecycle Event Commands

The CLI provides commands for managing agent lifecycle events:

Idle Notification

Send when an agent has no more work:

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

Shutdown Sequence

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

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

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

Sources: skills/clawteam/references/cli-reference.md

Plan Submission Events

Agents submit plans for leader approval, creating an approval workflow:

sequenceDiagram
    Agent->>Leader: plan submit <team> <agent> <plan-content>
    Note over Leader: Reviews plan
    Leader->>Agent: plan approve <team> <plan-id> <agent>
    Note over Agent: Plan approved, proceed with work

Plan Commands

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

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

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

Sources: skills/clawteam/references/cli-reference.md

Context Recovery Hooks

The harness system integrates with the event system through context recovery hooks that provide role-aware information to agents:

def _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:
    """Layer 5: One-liner teammate summaries."""
    from clawteam.team.models import TaskStatus
    from clawteam.team.tasks import TaskStore
    store = TaskStore(team_name)
    tasks = store.list_tasks()

Sources: clawteam/harness/context_recovery.py:53-59

Different roles receive different context:

Sources: clawteam/harness/context_recovery.py:31-47

Spawn Backend Event Integration

The wsh backend demonstrates how spawned agents integrate with the event system for runtime message injection:

def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
    """Best-effort runtime injection into a running wsh block."""
    from clawteam.spawn.registry import get_registry

    info = get_registry(team).get(agent_name, {})
    block_id = info.get("block_id", "") or self._blocks.get(agent_name, "")
    if not block_id:
        return False, f"wsh block for '{team}/{agent_name}' not found"

The spawn registry tracks agent metadata (team_name, agent_name, backend, block_id, pid, command) enabling the event system to route messages to correct agent processes.

Sources: clawteam/spawn/wsh_backend.py:52-61

See Also

• CLI Reference — Complete command documentation
• Task System — Task management and dependencies
• Spawn System — Agent spawning and backend management

Related Pages

Related topics: Quick Start Guide, Team Management

Agent Spawning System

The Agent Spawning System is the core infrastructure in ClawTeam responsible for launching, managing, and coordinating multiple AI agent processes. It provides a unified interface to spawn various CLI-based agents (such as Claude Code, Codex, Gemini, nanobot, and OpenClaw) within a team context, handling environment setup, session persistence, and lifecycle management.

Architecture Overview

The spawning system follows a pluggable backend architecture that abstracts the underlying execution environment. This design allows ClawTeam to support multiple execution backends while presenting a consistent API to the rest of the system.

graph TD
    A[CLI Command: clawteam spawn] --> B[SpawnCommand Handler]
    B --> C[Backend Factory]
    C --> D[subprocess Backend]
    C --> E[tmux Backend]
    C --> F[wsh Backend]
    D --> G[Agent Process]
    E --> H[tmux Session]
    F --> I[wsh Block]
    G --> J[Session Store]
    H --> J
    I --> J
    J --> K[Registry]
    K --> L[Team Coordination]

Core Components

Spawn Backends

The system supports three execution backends, each providing different isolation and management capabilities:

#### Base Backend Interface

All backends implement a common interface defined in base.py:

class SpawnBackend(ABC):
    @abstractmethod
    def spawn(
        self,
        command: list[str],
        team_name: str,
        agent_name: str,
        agent_type: str,
        cwd: str | None = None,
        env: dict[str, str] | None = None,
        **kwargs
    ) -> str:
        """Spawn an agent process and return result message."""
        pass
    
    @abstractmethod
    def list_running(self) -> list[dict[str, str]]:
        """List currently running agents."""
        pass
    
    @abstractmethod
    def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
        """Inject a runtime notification into a running agent."""
        pass

Sources: clawteam/spawn/base.py:1-50

Agent Registry

When an agent is spawned, it is registered in a centralized registry that tracks all active agents per team:

from clawteam.spawn.registry import register_agent

register_agent(
    team_name=team_name,
    agent_name=agent_name,
    backend="tmux",
    block_id=session_name,
    pid=process.pid,
    command=list(final_command),
)

Sources: clawteam/spawn/tmux_backend.py, clawteam/spawn/wsh_backend.py:1-50

The registry maintains the following information per agent:

• team_name: The team the agent belongs to
• agent_name: Unique identifier within the team
• backend: Backend type (subprocess/tmux/wsh)
• block_id / session_name: Backend-specific identifier
• pid: Process ID (for subprocess backend)
• command: Original spawn command

Spawn Command Interface

CLI Syntax

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

Command Options

Example Usage

# Spawn Claude Code agent in tmux
clawteam spawn tmux claude --team dev-team --agent-name builder --agent-type researcher

# Spawn in subprocess backend
clawteam spawn subprocess claude-code --team analysis --agent-name analyzer

Sources: skills/clawteam/references/cli-reference.md, clawteam/cli/commands.py

Agent Identity System

When spawning an agent, the system automatically configures environment variables that establish the agent's identity within the team:

export CLAWTEAM_AGENT_ID="<auto-generated-uuid>"
export CLAWTEAM_AGENT_NAME="<agent-name>"
export CLAWTEAM_AGENT_TYPE="<agent-type>"
export CLAWTEAM_TEAM_NAME="<team-name>"

Agents can verify their identity using:

clawteam identity show

Sources: clawteam/cli/commands.py, skills/clawteam/references/cli-reference.md

Session Management

Session Persistence

The system tracks agent sessions to enable resume functionality:

from clawteam.spawn.sessions import SessionStore

session_store = SessionStore(team_name)
session = session_store.load(agent_name)

if session and session.session_id:
    resumed_command = build_cli_resume_command(command, session.session_id, client=client)

Sources: clawteam/spawn/sessions.py, clawteam/spawn/session_capture.py

Session Lifecycle

graph LR
    A[Spawn] --> B[Create Session]
    B --> C[Store in SessionStore]
    C --> D[Execute Agent]
    D --> E[Agent Completes]
    E --> F[Session Archived]
    F --> G[Resume Available]
    G --> H[Resume Command]
    H --> D

Session Locators

Session locators find existing sessions across different backends:

from clawteam.spawn.session_locators.base import SessionLocator

class SessionLocator(ABC):
    @abstractmethod
    def find_session(self, team: str, agent: str) -> SessionInfo | None:
        """Locate an existing session for the given team/agent."""
        pass

Sources: clawteam/spawn/session_locators/base.py

Profile and Preset System

Profiles

Profiles are reusable configurations that define how agents should be spawned:

# List available profiles
clawteam profile list

# Test a profile
clawteam profile test claude-kimi

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

Sources: clawteam/spawn/profiles.py, skills/clawteam/SKILL.md

Presets

Presets are provider templates used to generate profiles:

# List presets
clawteam preset list

# Show preset details
clawteam preset show moonshot-cn

Sources: clawteam/spawn/presets.py, skills/clawteam/references/workflows.md

Prompt Generation

When spawning an agent, ClawTeam generates a comprehensive system prompt that includes identity information, task details, and coordination instructions:

from clawteam.spawn.prompt import build_agent_prompt

prompt = build_agent_prompt(
    agent_name=agent_name,
    agent_id=agent_id,
    agent_type=agent_type,
    team_name=team_name,
    leader_name=leader_name,
    task=task,
    user=user_name,
    workspace_dir=cwd,
    workspace_branch=ws_branch,
    isolated_workspace=bool(workspace and cwd),
    repo_path=repo,
)

Sources: clawteam/spawn/prompt.py, clawteam/cli/commands.py

Prompt Components

The generated prompt includes:

1. Identity block: Agent name, ID, type, and team
2. Task description: Assigned work from the team leader
3. Coordination guide: How to use ClawTeam CLI for task updates
4. Workspace context: Directory, branch, git state

Skill Loading

Agents can be spawned with predefined skills loaded from ~/.claude/skills/:

def _load_skill_content(name: str) -> str | None:
    """Load skill content from ~/.claude/skills."""
    skills_root = Path.home() / ".claude" / "skills"
    skill_dir = skills_root / name
    
    # Support both directory and single-file formats
    if skill_dir.is_dir():
        skill_file = skill_dir / "SKILL.md"
        # Fallback to first .md file
    else:
        single_file = skills_root / f"{name}.md"

Sources: clawteam/cli/commands.py

Supported Skill Formats

• Directory format: skills/<name>/SKILL.md
• Single file format: skills/<name>.md

Runtime Message Injection

The system supports injecting runtime notifications into running agents:

def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
    """Best-effort runtime injection into a running agent."""
    from clawteam.spawn.registry import get_registry
    
    info = get_registry(team).get(agent_name, {})
    block_id = info.get("block_id", "")
    
    if not block_id:
        return False, f"Agent '{team}/{agent_name}' not found"
    
    # Render and send notification
    payload = render_runtime_notification(envelope)

Sources: clawteam/spawn/wsh_backend.py, clawteam/spawn/base.py

Team Template Launch

For complex multi-agent scenarios, ClawTeam supports launching entire teams from templates:

clawteam launch <template> <backend> [options]

Launch Options

Template Structure

team_template = {
    "name": "dev-team",
    "leader": {"name": "leader", "type": "leader"},
    "members": [
        {"name": "researcher", "type": "researcher"},
        {"name": "coder", "type": "general-purpose"},
    ]
}

Sources: clawteam/cli/commands.py, skills/clawteam/SKILL.md

Backend-Specific Details

TMUX Backend

The tmux backend creates named sessions for each agent:

tmux new-session -d -s clawteam-{team}-{agent} "{command}"
tmux attach -t clawteam-{team}-{agent}

Sessions are named using pattern: clawteam-{team_name}-{agent_name}

Sources: clawteam/spawn/tmux_backend.py

Subprocess Backend

The subprocess backend provides direct process management:

process = subprocess.Popen(
    command,
    env=full_env,
    cwd=cwd,
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
)

Sources: clawteam/spawn/subprocess_backend.py

WSH Backend

The weish backend provides block-based isolation:

pane_id = spawn_wsh_block(
    target=target,
    command=final_command,
    title=agent_name,
)

Sources: clawteam/spawn/wsh_backend.py

Configuration Files

Profile Configuration

Profiles are stored in JSON format:

{
  "name": "claude-kimi",
  "provider": "moonshot-cn",
  "api_key_env": "MOONSHOT_API_KEY",
  "model": "claude-3-5-sonnet",
  "spawn_options": {
    "backend": "tmux",
    "agent_type": "general-purpose"
  }
}

Preset Configuration

Presets define provider templates:

{
  "name": "moonshot-cn",
  "provider": "openai-compatible",
  "base_url": "https://api.moonshot.cn/v1",
  "models": ["claude-3-5-sonnet", "claude-3-sonnet"]
}

Sources: clawteam/spawn/profiles.py, clawteam/spawn/presets.py

Error Handling

Common Errors and Solutions

Spawn Hint System

The CLI provides contextual hints when arguments are misordered:

def _spawn_hint(backend: str | None, team: str | None) -> str:
    """Provide helpful hint when spawn positional args are misordered."""
    if not backend or team:
        return ""
    return (
        " Hint: the first positional argument to `clawteam spawn` is the backend "
        "(`tmux` or `subprocess`), not the team name. Use `--team <name>` to set "
        "the team explicitly."
    )

Sources: clawteam/cli/commands.py

Workflow Diagram

sequenceDiagram
    participant User
    participant CLI
    participant Backend
    participant Registry
    participant Agent

    User->>CLI: clawteam spawn tmux claude --team dev --name worker1
    CLI->>Backend: spawn(command, team, agent)
    Backend->>Backend: Setup environment
    Backend->>Backend: Create tmux session
    Backend->>Agent: Launch agent process
    Backend->>Registry: register_agent(...)
    Registry-->>CLI: Agent registered
    CLI-->>User: "Agent 'worker1' spawned in tmux"
    Agent->>Agent: Read identity env vars
    Agent->>Agent: Execute assigned task

Best Practices

1. Use descriptive agent names: Makes tracking and debugging easier
2. Set appropriate agent types: Enables role-based task assignment
3. Use tmux backend for persistence: Allows attaching to view progress
4. Leverage profiles: Reuse configurations across multiple spawns
5. Use session resume: Maintain continuity across agent restarts

See Also

• CLI Reference - Full command documentation
• Workflows - Common usage patterns
• Team Management - Team operations

Related Pages

Related topics: Agent Spawning System, Messaging & Inbox System, Board & Monitoring Dashboard

Task Management System

Overview

The Task Management System is the core orchestration layer within ClawTeam that enables multi-agent teams to create, track, assign, and coordinate work items across collaborative agent swarms. It provides a task store abstraction with file-based persistence, supporting task dependencies, priority levels, status tracking, and automatic unblocking when dependent tasks complete.

Sources: clawteam/team/tasks.py:1-17

Related Pages

Related topics: Agent Spawning System, Task Management System, Event System

Team Management

Team Management is the core orchestration layer in ClawTeam that enables multiple AI agents to collaborate within a structured hierarchy. It provides facilities for creating teams, managing agent lifecycles, routing messages, coordinating tasks with dependency chains, and facilitating graceful shutdowns.

Overview

ClawTeam's Team Management system treats a multi-agent workflow as a first-class organizational unit called a Team. Each team has:

• A designated Leader agent responsible for coordination
• Member agents with distinct roles and capabilities
• A shared Board for task visualization and status tracking
• An Inbox system for point-to-point and broadcast messaging
• Task management with dependency tracking

Sources: skills/clawteam/references/cli-reference.md

Team Architecture

graph TD
    A[Leader Agent] --> B[Board - Kanban Tasks]
    A --> C[Inbox - Message Routing]
    A --> D[Task Store]
    B --> E[Task Status: pending, in_progress, completed, blocked]
    C --> F[Message Types: broadcast, plan, shutdown, idle]
    D --> G[Dependency Chains]

The architecture follows a hub-and-spoke model where the leader agent serves as the central coordinator. The Board provides a kanban-style visualization, while the Inbox handles all inter-agent communication.

Sources: clawteam/team/manager.py

Team Lifecycle

Lifecycle States

Agents in a team progress through well-defined lifecycle states:

Sources: clawteam/team/lifecycle.py

Lifecycle Commands

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

# Agent approves shutdown
clawteam lifecycle approve-shutdown <team> <request-id> <agent>

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

# Agent signals idle state to leader
clawteam lifecycle idle <team> [--last-task ID] [--task-status STATUS]

Sources: skills/clawteam/references/workflows.md

Message Routing

The routing system determines how messages flow between agents within a team.

graph LR
    A[Agent A] -->|message| B[Router]
    A -->|broadcast| B
    A -->|plan_approval_request| B
    B -->|route| C[Agent B]
    B -->|route| D[All Members]
    B -->|route| E[Leader]

Routing Policies

Sources: clawteam/team/router.py Sources: clawteam/team/routing_policy.py

Message Types

Sources: skills/clawteam/references/cli-reference.md

Task Management

Tasks are the fundamental work units within a team. They support dependency chains, priorities, and automatic status transitions.

Task Statuses

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

Sources: clawteam/team/tasks.py

Task Commands

# Create a task
clawteam task create <team> <subject> [options]
    -o, --owner NAME          Task owner
    -d, --description TEXT    Task description
    -p, --priority LEVEL      low, medium, high, urgent
    --blocks ID               Task IDs this blocks
    --blocked-by ID           Comma-separated task IDs blocking this

# Update task
clawteam task update <team> <task-id> [options]
    -s, --status STATUS       New status
    -o, --owner NAME          New owner
    --add-blocks ID           Add tasks this blocks
    --add-blocked-by ID       Add tasks blocking this
    -f, --force               Force override task lock

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

# Get single task
clawteam task get <team> <task-id>

Task Dependency Example

# Task 1: Design system (no dependencies)
clawteam task create my-project "Design system" -o leader
# => Task ID: aaa11111

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

# Task 3: Integration testing (blocked by Tasks 1 and 2)
clawteam task create my-project "Integration testing" --blocked-by bbb22222,ccc33333
# => Task ID: ddd44444

# When Task 1 completes, Task 2 unblocks
clawteam task update my-project aaa11111 --status completed

Sources: skills/clawteam/references/workflows.md

Agent Roles

ClawTeam supports role-based agent assignments through the harness system.

Available Roles

Sources: clawteam/harness/roles.py

Role-Specific Context Recovery

Each role has context recovery layers that inject relevant information:

Sources: clawteam/harness/context_recovery.py

Orchestration

The orchestrator coordinates multiple agents within a team template, spawning agents with proper identity and environment setup.

Orchestration Flow

sequenceDiagram
    participant L as Leader
    participant O as Orchestrator
    participant A as Agent
    participant S as Spawn Backend

    L->>O: Launch team from template
    O->>O: Parse template and roles
    loop For each agent
        O->>S: Spawn agent with identity env vars
        S->>A: Start agent process
        A->>A: Set CLAWTEAM_AGENT_* vars
    end
    O->>L: Return launch summary

Spawn Command

clawteam spawn <backend> <command...> [options]
    -t, --team NAME         Team name (default: "default")
    -n, --agent-name NAME   Agent name (auto-generated)
    --agent-type TYPE       Agent type (default: "general-purpose")

Backends: subprocess, tmux

Example:

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

Sources: clawteam/cli/commands.py

Board and Monitoring

The Board provides real-time visualization of team state.

Board Commands

# Show detailed team board (kanban view)
clawteam board show <team>
clawteam --json board show <team>

# Overview of all teams
clawteam board overview
clawteam --json board overview

# Live-refreshing kanban board
clawteam board live <team> [--interval 2.0]

Board Data Structure

The board includes:

• Kanban task visualization with status badges
• Member inbox counts
• Message history from event log
• Member-aware message aliases (memberKey, inboxName, fromLabel, toLabel)

Sources: skills/clawteam/references/cli-reference.md

Team Snapshots

Snapshots capture the complete state of a team at a point in time for debugging, auditing, or resumption.

graph TD
    A[Snapshot Request] --> B[Snapshot Generator]
    B --> C[Team Config]
    B --> D[Task States]
    B --> E[Agent Status]
    B --> F[Message History]
    B --> G[File Storage: ~/.clawteam/teams/{team}/]

Sources: clawteam/team/snapshot.py

File Storage Layout

Team data persists to disk under ~/.clawteam/:

~/.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

Sources: skills/clawteam/references/cli-reference.md

Workflow: Complete Team Lifecycle

graph TD
    A[Create Team] --> B[Spawn Agents]
    B --> C[Assign Tasks]
    C --> D[Agent Work]
    D --> E{Status}
    E -->|in_progress| D
    E -->|completed| F[Unblock Dependents]
    E -->|idle| G[Report to Leader]
    F --> H{Tasks Remaining?}
    H -->|Yes| D
    H -->|No| I[Request Shutdown]
    I --> J[Approve Shutdown]
    J --> K[Cleanup Team]

Step-by-Step Workflow

``bash clawteam team spawn-team my-team -d "Project team" -n leader ``

1. Create team with leader

``bash clawteam spawn tmux claude --team my-team --agent-name researcher clawteam spawn tmux claude --team my-team --agent-name coder ``

1. Spawn worker agents

``bash clawteam task create my-team "Research phase" -o researcher clawteam task create my-team "Implementation" -o coder --blocked-by <research-task-id> ``

1. Create and assign tasks

``bash clawteam board live my-team ``

1. Monitor progress

``bash clawteam lifecycle request-shutdown my-team leader coder clawteam lifecycle approve-shutdown my-team <request-id> coder clawteam team cleanup my-team --force ``

1. Graceful shutdown

Sources: skills/clawteam/references/workflows.md

Quick Reference: Team Commands

Sources: clawteam/cli/commands.py

Related Pages

Related topics: System Architecture, Messaging & Inbox System

# Transport Layer

## Overview

The Transport Layer in ClawTeam is a modular communication subsystem that enables inter-agent messaging within a team. It provides abstract interfaces and concrete implementations for different transport mechanisms, allowing agents to send, receive, and route messages regardless of the underlying delivery mechanism.

The transport layer is designed with a pluggable architecture, supporting multiple backends including file-based transport and peer-to-peer (P2P) transport for direct agent-to-agent communication.

## Architecture

graph TB subgraph "Transport Layer" API[Transport API] BASE[BaseTransport] FILE[FileTransport] P2P[P2PTransport] CLM[ClaimedTransport] end

subgraph "Message Flow" SND[Sender Agent] RCV[Receiver Agent] INBOX[Inbox Store] end

API --> BASE BASE --> FILE BASE --> P2P BASE --> CLM

SND -->|send_message| API API --> INBOX INBOX --> RCV

## Core Components

### Base Transport (`clawteam/transport/base.py`)

The `BaseTransport` abstract class defines the interface that all transport implementations must follow.

| Method | Purpose |
|--------|---------|
| `send(envelope)` | Send a message envelope to destination |
| `receive(agent_name)` | Retrieve messages from agent's inbox |
| `peek(agent_name)` | View messages without consumption |
| `list_pending(agent_name)` | List pending message IDs |

Sources: [clawteam/transport/base.py]()

### File Transport (`clawteam/transport/file.py`)

File-based transport provides reliable message delivery using filesystem-based inboxes. Messages are stored as JSON files in the team's inbox directory structure.

~/.clawteam/ ├── teams/{team}/ │ └── inboxes/{agent}/ │ └── msg-{timestamp}-{uuid}.json

Sources: [clawteam/transport/file.py]()

**Key Features:**
- Persistent message storage
- Non-destructive `peek` operations
- Destructive `receive` operations
- Atomic file operations for consistency

### P2P Transport (`clawteam/transport/p2p.py`)

Peer-to-peer transport enables direct agent-to-agent communication without centralized message storage. This is an optional backend that requires the `p2p` extra: `pip install "clawteam[p2p]"`

Sources: [clawteam/transport/p2p.py]()

**Use Cases:**
- Low-latency communication
- Decentralized team topologies
- Environments without shared filesystem

### Claimed Transport (`clawteam/transport/claimed.py`)

The `ClaimedTransport` wraps another transport backend and adds message claiming semantics. This prevents duplicate message processing in concurrent scenarios.

Sources: [clawteam/transport/claimed.py]()

## Message Envelope

Messages are encapsulated in an envelope structure containing routing and payload information.

@dataclass class Envelope: to: str # Destination agent name from_: str # Source agent name msg_type: str # Message type identifier payload: dict # Message content timestamp: float # Unix timestamp id: str # Unique message ID

## Message Types

| Type | Description | Used By |
|------|-------------|---------|
| `message` | General point-to-point message | Core |
| `broadcast` | Broadcast to all team members | Core |
| `join_request` | Request to join a team | Team module |
| `join_approved` / `join_rejected` | Join response | Team module |
| `plan_approval_request` | Plan submitted for review | Plan module |
| `plan_approved` / `plan_rejected` | Plan response | Plan module |
| `shutdown_request` | Agent shutdown request | Lifecycle module |
| `shutdown_approved` / `shutdown_rejected` | Shutdown response | Lifecycle module |
| `idle` | Agent idle notification | Lifecycle module |

Sources: [clawteam/transport/__init__.py]()

## Transport Selection

graph LR A[Agent Spawns] --> B{Configured Backend} B -->|default| F[FileTransport] B -->|p2p| P[P2PTransport] B -->|claimed| C[ClaimedTransport]

The transport backend is typically specified in the agent's runtime profile or configured via environment variables.

## Configuration

Transport backends can be configured through:

1. **Runtime Profiles** - Stored in `~/.clawteam/profiles/`
2. **Environment Variables** - `CLAWTEAM_TRANSPORT_BACKEND`
3. **Profile Wizard** - Interactive TUI: `clawteam profile wizard`

Sources: [skills/clawteam/SKILL.md]()

Related Pages

Related topics: Transport Layer, Agent Spawning System

Messaging & Inbox System

Overview

The Messaging & Inbox System in ClawTeam provides inter-agent communication capabilities for coordinating agent swarms. It enables point-to-point messaging, broadcasts, and structured request/response patterns for team coordination including plan approvals, join requests, and graceful shutdowns.

Messages are stored persistently in team-specific inboxes as JSON files, allowing asynchronous communication between agents that may not be running simultaneously. Each agent has its own inbox within a team's directory structure at ~/.clawteam/teams/{team}/inboxes/{agent}/. Sources: skills/clawteam/references/cli-reference.md

Architecture

graph TD
    A[Agent] -->|mailbox_send| B[TeamMailbox]
    A -->|mailbox_receive| B
    A -->|mailbox_broadcast| B
    B --> C[File System]
    C --> D[~/.clawteam/teams/{team}/inboxes/]
    E[Leader] -->|Plan messages| B
    F[Worker] -->|Plan messages| B
    
    subgraph "Message Types"
        G[message]
        H[broadcast]
        I[join_request]
        J[plan_approval_request]
        K[shutdown_request]
        L[idle]
    end

Message Types

The system supports the following message types defined in the MessageType enum:

Sources: clawteam/team/plan.py:12-40

Core API Functions

mailbox_send

Send a message to a specific agent within a team.

def mailbox_send(
    team_name: str,
    from_agent: str,
    to_agent: str,
    content: str,
    msg_type: str | None = None,
    request_id: str | None = None,
    key: str | None = None,
    proposed_name: str | None = None,
    capabilities: str | None = None,
    feedback: str | None = None,
    reason: str | None = None,
    assigned_name: str | None = None,
    agent_id: str | None = None,
    team_name: str | None = None,
    plan_file: str | None = None,
    summary: str | None = None,
    plan: str | None = None,
    last_task: str | None = None,
    status: str | None = None,
) -> dict

Sources: clawteam/mcp/tools/mailbox.py

mailbox_broadcast

Broadcast a message to all team members, with optional exclusions.

def mailbox_broadcast(
    team_name: str,
    from_agent: str,
    content: str,
    msg_type: str | None = None,
    key: str | None = None,
    exclude: list[str] | None = None,
) -> list[dict]

Sources: clawteam/mcp/tools/mailbox.py:28-41

mailbox_receive

Receive and consume pending inbox messages. Messages are removed from the inbox after retrieval.

def mailbox_receive(
    team_name: str,
    agent_name: str,
    limit: int = 10,
) -> list[dict]

Sources: clawteam/mcp/tools/mailbox.py:44-47

mailbox_peek

Preview pending inbox messages without consuming them. Messages remain available for future retrieval.

def mailbox_peek(
    team_name: str,
    agent_name: str,
) -> list[dict]

Sources: clawteam/mcp/tools/mailbox.py:50-53

mailbox_peek_count

Get the count of pending messages without retrieving content.

def mailbox_peek_count(
    team_name: str,
    agent_name: str,
) -> dict

Returns:

{
  "agentName": "alice",
  "count": 5
}

Sources: clawteam/mcp/tools/mailbox.py:56-59

CLI Commands

inbox send

Send a message to another agent.

clawteam inbox send <team> <from-agent> <to-agent> <content> [--type TYPE]

inbox receive

Receive and consume pending messages.

clawteam inbox receive <team> --agent <agent-name> [--limit N]

inbox peek

Preview messages without consuming.

clawteam inbox peek <team> --agent <agent-name>

inbox count

Count pending messages.

clawteam inbox count <team> --agent <agent-name>

inbox broadcast

Broadcast to all team members.

clawteam inbox broadcast <team> <from-agent> <content> [--exclude AGENT1,AGENT2]

Sources: skills/clawteam/references/cli-reference.md

Message Flow Patterns

Point-to-Point Messaging

sequenceDiagram
    participant A as Agent Alice
    participant M as TeamMailbox
    participant B as Agent Bob
    
    A->>M: mailbox_send(to=Bob, content="Task update")
    M->>M: Store msg-{timestamp}-{uuid}.json
    B->>M: mailbox_receive(agent=Bob)
    M->>B: Return and remove message

Plan Approval Flow

graph LR
    A[Worker] -->|plan_approval_request| B[Leader]
    B -->|Review| B
    B -->|plan_approved| A
    B -->|plan_rejected| A

Example workflow:

# Worker submits plan
clawteam plan submit dev-team coder "Auth system redesign" \
  --summary "Modernize auth system"

# Leader reviews 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"

Sources: skills/clawteam/references/workflows.md

Shutdown Flow

sequenceDiagram
    participant L as Leader
    participant M as TeamMailbox
    participant W as Worker
    
    L->>M: lifecycle request-shutdown
    M->>W: shutdown_request
    W->>W: Complete current work
    W->>M: lifecycle approve-shutdown
    M->>L: shutdown_approved

Sources: skills/clawteam/references/workflows.md

Storage Layout

Messages are persisted in the following structure:

~/.clawteam/
├── teams/{team}/
│   └── inboxes/
│       └── {agent}/
│           ├── msg-{timestamp}-{uuid}.json   # Individual messages
│           ├── msg-{timestamp}-{uuid}.json
│           └── ...
└── plans/
    └── {agent}-{id}.md                        # Plan documents

Each message file contains structured JSON with metadata including sender, recipient, message type, timestamp, and type-specific fields.

Sources: skills/clawteam/references/cli-reference.md

Data Model

Message Payload

@dataclass
class MessagePayload:
    msg_type: MessageType
    from_agent: str
    to_agent: str
    content: str
    request_id: str | None
    key: str | None
    proposed_name: str | None
    capabilities: str | None
    feedback: str | None
    reason: str | None
    assigned_name: str | None
    agent_id: str | None
    team_name: str | None
    plan_file: str | None
    summary: str | None
    plan: str | None
    last_task: str | None
    status: str | None

Sources: clawteam/mcp/tools/mailbox.py:1-20

Best Practices

1. Always check inbox before declaring idle - Agents should check clawteam task list {team} and inbox before reporting idle status.

1. Use peek before receive - Preview messages with mailbox_peek when you need to selectively process messages without consuming all pending items.

1. Set request IDs for tracking - When sending plan or shutdown requests, include a unique request_id to correlate responses.

``bash clawteam cost report {team} --input-tokens <N> --output-tokens <N> --cost-cents <N> ``

1. Send cost reports - After completing work, report costs using:

``bash clawteam --json board show dev-team | jq '.members[] | select(.inboxCount > 0) | .name' ``

1. Monitor team health - Use JSON output for scripting:

Sources: clawteam/spawn/prompt.py

Related Pages

Related topics: Task Management System, Team Management

Board & Monitoring Dashboard

The Board is ClawTeam's centralized monitoring and coordination interface for agent swarms. It provides real-time visibility into team tasks, agent statuses, message exchanges, and activity history through both CLI commands and a browser-based dashboard.

Purpose & Scope

The Board system serves as the coordination nerve center for multi-agent teams:

• Task Visualization — Kanban-style task boards showing blockers, priority, ownership, and progress across all agents
• Persistent Coordination — Handoffs, aliases, and notes remain visible after prompts scroll away
• Team Awareness — Inbox counts, member status, and message history accessible in one view
• Activity Visualization — Gource-based git activity rendering to visualize team contributions over time

Sources: skills/clawteam/SKILL.md

Architecture

graph TD
    subgraph "Board Subsystem"
        A[board show] --> B[Board Server]
        C[board live] --> B
        D[board overview] --> B
        
        B --> E[Collector Module]
        B --> F[Renderer Module]
        B --> G[Gource Module]
        
        E --> H[Task Store]
        E --> I[Message Store]
        E --> J[Team Config]
    end
    
    subgraph "Output Formats"
        F --> K[Human Readable]
        F --> L[JSON API]
        G --> M[Gource Visualization]
    end

The Board module consists of four primary components:

Sources: clawteam/board/server.py

Data Model

The Board draws data from three primary storage locations under ~/.clawteam/:

~/.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

Task Statuses

Sources: skills/clawteam/references/cli-reference.md

Message Types

Sources: skills/clawteam/references/cli-reference.md

Board Commands

`board show`

Display detailed team board data with kanban visualization.

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

The JSON output includes member-aware message aliases:

• memberKey — Unique member identifier
• inboxName — Agent's inbox directory name
• fromLabel / toLabel — Human-readable sender/recipient labels

These fields enable the browser board to filter inbox history by team member.

Sources: skills/clawteam/references/cli-reference.md

`board overview`

Show summary of all teams in a table format.

clawteam board overview
clawteam --json board overview

Returns metadata for each team:

`board live`

Launch a live-refreshing kanban board that auto-updates at configurable intervals.

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

Press Ctrl+C to stop the live view. Default refresh interval is 2.0 seconds.

Sources: skills/clawteam/references/cli-reference.md

MCP Board Tools

For integration with AI agents, the Board exposes MCP (Model Context Protocol) tools in clawteam/mcp/tools/board.py:

# Available MCP tools for board interaction
- board_show       # Show team board data
- board_overview   # List all teams summary
- board_live       # Start live monitoring

These tools allow AI agents to query board state programmatically without CLI invocation.

Sources: clawteam/mcp/tools/board.py

Browser Dashboard (website/src/App.jsx)

The website provides a browser-accessible board interface at website/src/App.jsx. The browser board includes:

Visual Components

The TerminalMockup component renders a simulated CLI session showing team operations:

<TeamTerminalMockup/>

This mockup demonstrates:

• Team creation: clawteam team spawn-team docs-sprint
• Agent spawning: clawteam spawn tmux claude-code --agent-name builder
• Status checks: clawteam team status docs-sprint

Sources: website/src/App.jsx

Gource Activity Visualization

The gource.py module provides git-aware execution visualization:

graph LR
    A[Git Repos] --> B[Gource Renderer]
    C[Worktrees] --> B
    D[Diffs] --> B
    E[Merge State] --> B
    
    B --> F[Activity Timeline]

Gource renders agent activity as a timeline visualization, showing:

• File changes over time
• Agent contribution patterns
• Merge and branch activity

Sources: clawteam/board/gource.py

Integration with Task System

The Board integrates closely with the task management system:

graph LR
    A[Task Create] --> B[Task Store]
    C[Task Update] --> B
    D[Task Complete] --> E[Auto-Unblock]
    
    B --> F[Board Collector]
    F --> G[Board Renderer]
    G --> H[CLI / Browser]
    
    E --> B

Task commands that feed into the Board:

When a task is marked completed, the system automatically unblocks any tasks that were blocked by it (moving them from blocked to pending if no other blockers remain).

Sources: skills/clawteam/references/cli-reference.md

Configuration

Board behavior is controlled through team configuration stored in ~/.clawteam/teams/{team}/config.json:

{
  "name": "team-name",
  "members": ["leader", "agent-1", "agent-2"],
  "leader": "leader"
}

The collector module reads this config along with task and message stores to build the complete board view.

Sources: clawteam/board/collector.py

Quick Reference

Doramagic Pitfall Log

Doramagic extracted 15 source-linked risk signals. Review them before installing or handing real data to the project.

1. Security or permission risk: Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/HKUDS/ClawTeam/issues/76

2. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | host_targets=claude, claude_code, cursor, chatgpt

3. Configuration risk: Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/HKUDS/ClawTeam/issues/157

4. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | README/documentation is current enough for a first validation pass.

5. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | last_activity_observed missing

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium

7. Security or permission risk: No sandbox install has been executed yet; downstream must verify before user use.

• Severity: medium
• Finding: No sandbox install has been executed yet; downstream must verify before user use.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.safety_notes | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | No sandbox install has been executed yet; downstream must verify before user use.

8. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium

9. Security or permission risk: Agent Definitions Feature is Non-Functional: Parsed but Not Applied

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: Agent Definitions Feature is Non-Functional: Parsed but Not Applied. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/HKUDS/ClawTeam/issues/146

10. Security or permission risk: High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/HKUDS/ClawTeam/issues/104

11. Security or permission risk: Worker agents exit after first turn despite 'ongoing job' task prompt

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: Worker agents exit after first turn despite 'ongoing job' task prompt. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/HKUDS/ClawTeam/issues/148

12. Security or permission risk: [Feature Request] Optimize Worker Workspace Size and Enable Headless IPC

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: [Feature Request] Optimize Worker Workspace Size and Enable Headless IPC. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/HKUDS/ClawTeam/issues/45

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ClawTeam with real data or production workflows.

• Proposal: 8-PR sequence — canonical WorkerState, persistent event log, p - github / github_issue
• Security testing for multi-agent swarms: agent isolation, delegation tru - github / github_issue
• Agent Definitions Feature is Non-Functional: Parsed but Not Applied - github / github_issue
• Worker agents exit after first turn despite 'ongoing job' task prompt - github / github_issue
• [[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC](https://github.com/HKUDS/ClawTeam/issues/45) - github / github_issue
• High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetc - github / github_issue
• v0.2.0 — Stabilization Release - github / github_release
• This is the Claude Code Resource Bible. 54 tools. Agents. MCP ... - x / searxng_indexed
• This is the Claude Code Resource Bible. 54 tools. Agents. MCP ... - x / searxng_indexed
• This is the Claude Code Resource Bible. 54 tools. Agents. MCP ... - x / searxng_indexed
• This is the Claude Code Resource Bible. 54 tools. Agents. MCP ... - x / searxng_indexed
• This is the Claude Code Resource Bible. 54 tools. Agents. MCP ... - x / searxng_indexed