# https://github.com/HKUDS/ClawTeam 项目说明书 生成时间：2026-05-17 05:40:48 UTC ## 目录 - [Introduction to ClawTeam](#page-introduction) - [Quick Start Guide](#page-quickstart) - [System Architecture](#page-architecture) - [Event System](#page-event-system) - [Agent Spawning System](#page-agent-spawning) - [Task Management System](#page-task-management) - [Team Management](#page-team-management) - [Transport Layer](#page-transport) - [Messaging & Inbox System](#page-messaging) - [Board & Monitoring Dashboard](#page-board-dashboard) ## Introduction to ClawTeam ### 相关页面 相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart)
Relevant Source Files 以下源码文件用于生成本页说明： - [website/src/App.jsx](https://github.com/HKUDS/ClawTeam/blob/main/website/src/App.jsx) - [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) - [skills/clawteam/SKILL.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/SKILL.md) - [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py) - [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py) - [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py) - [clawteam/spawn/session_locators/claude.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_locators/claude.py)
# 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 资料来源：[skills/clawteam/SKILL.md]() ## Architecture Overview ClawTeam follows a leader-worker architecture where one agent serves as the coordinator while others perform specialized tasks. ```mermaid 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 | Component | Description | |-----------|-------------| | **CLI Interface** | Command-line entry point for all operations | | **Team Manager** | Handles team creation, membership, and discovery | | **Task Store** | File-based task board with dependency chains | | **Message Inbox** | Per-agent file-based message queue | | **Spawn Backends** | tmux, subprocess, wsh for launching agents | | **Session Locators** | Detects and captures existing agent sessions | 资料来源：[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 ``` 资料来源：[skills/clawteam/references/cli-reference.md]() ## Task Management System Tasks form the backbone of team coordination, supporting four distinct statuses: | Status | Description | |--------|-------------| | `pending` | Not yet started | | `in_progress` | Currently being worked on | | `completed` | Done (auto-unblocks dependents) | | `blocked` | Waiting on other tasks | ### 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). 资料来源：[skills/clawteam/references/cli-reference.md]() ```mermaid 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: | Type | Description | |------|-------------| | `message` | General point-to-point message | | `broadcast` | Broadcast to all members | | `join_request` | Request to join team | | `join_approved` / `join_rejected` | Join response | | `plan_approval_request` | Plan submitted for review | | `plan_approved` / `plan_rejected` | Plan response | | `shutdown_request` | Shutdown request | | `shutdown_approved` / `shutdown_rejected` | Shutdown response | | `idle` | Agent idle notification | 资料来源：[skills/clawteam/references/cli-reference.md]() ## Spawn Backends ClawTeam supports multiple spawn backends for launching agents: | Backend | Description | |---------|-------------| | `tmux` | Default backend, sessions in tmux panes | | `subprocess` | Direct subprocess spawning | | `wsh` | WebSocket handler for IDE integration | The spawn command configures team environment variables for spawned agents: ```bash clawteam spawn [options] ``` | Option | Description | Default | |--------|-------------|---------| | `--team, -t` | Team name | `"default"` | | `--agent-name, -n` | Agent name | auto-generated | | `--agent-type` | Agent type | `"general-purpose"` | 资料来源：[clawteam/spawn/wsh_backend.py:1-30]() ## Session Management For Claude Code specifically, ClawTeam integrates with existing sessions: ```python # 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) 资料来源：[clawteam/spawn/session_locators/claude.py:1-60]() ## Lifecycle Management Agents support a complete lifecycle for graceful shutdown: ```mermaid 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 | Command | Purpose | |---------|---------| | `lifecycle request-shutdown` | Request an agent to shut down | | `lifecycle approve-shutdown` | Agent agrees to shut down | | `lifecycle reject-shutdown` | Agent rejects shutdown request | | `lifecycle idle` | Send idle notification to leader | 资料来源：[skills/clawteam/references/cli-reference.md]() ## Quick Start ### Installation ```bash clawteam --version # Check if installed pip install clawteam # Requires Python 3.10+ ``` ### Create and Manage a Team ```bash # 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 ```bash clawteam spawn tmux claude-code --team my-team --agent-name builder clawteam spawn tmux claude-code --team my-team --agent-name reviewer ``` 资料来源：[skills/clawteam/SKILL.md]() ## Board Dashboard The board command provides team visibility through multiple views: | Command | Description | |---------|-------------| | `board show` | Detailed kanban board with message history | | `board overview` | Summary of all teams in table format | | `board live` | Live-refreshing kanban board with auto-refresh | ```bash # JSON output for integration clawteam --json board show my-team # Live monitoring clawteam board live my-team --interval 2.0 ``` 资料来源：[skills/clawteam/references/cli-reference.md]() ## Identity System Each agent requires environment variables for identification within the team: ```bash 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.) 资料来源：[clawteam/harness/context_recovery.py:1-40]() ## Context Recovery The harness system provides role-based context recovery for agents: ```python # 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. 资料来源：[clawteam/harness/context_recovery.py:40-70]() ## See Also - [CLI Reference](skills/clawteam/references/cli-reference.md) - Complete command documentation - [SKILL.md](skills/clawteam/SKILL.md) - Comprehensive usage guide --- ## Quick Start Guide ### 相关页面 相关主题：[Introduction to ClawTeam](#page-introduction), [Agent Spawning System](#page-agent-spawning)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/HKUDS/ClawTeam/blob/main/README.md) - [pyproject.toml](https://github.com/HKUDS/ClawTeam/blob/main/pyproject.toml) - [skills/clawteam/SKILL.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/SKILL.md) - [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) - [clawteam/spawn/session_locators/claude.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_locators/claude.py) - [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)
# 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: | Requirement | Version/Details | Notes | |-------------|-----------------|-------| | Python | 3.10+ | Required runtime | | tmux | Latest | Default spawn backend | | Git | Any recent version | For worktree isolation and context features | | Coding Agent CLI | Claude, Codex, Gemini, etc. | At least one agent client installed | 资料来源：[skills/clawteam/SKILL.md:20-30]() ## Installation ### Standard Installation Install ClawTeam via pip: ```bash pip install clawteam ``` ### Installation with P2P Transport Support For peer-to-peer transport capabilities: ```bash pip install "clawteam[p2p]" ``` ### Verify Installation Confirm ClawTeam is installed correctly: ```bash clawteam --version ``` 资料来源：[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. 资料来源：[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). 资料来源：[skills/clawteam/references/cli-reference.md:80-88]() ### Inbox File-based message queue per agent. Messages can be destructive (`receive`) or non-destructive (`peek`). 资料来源：[skills/clawteam/SKILL.md:34]() ### Spawn Backends ClawTeam supports multiple agent spawning backends: | Backend | Description | Use Case | |---------|-------------|----------| | `subprocess` | Spawns agent as subprocess | Simple local execution | | `tmux` | Spawns agent in tmux session | Persistent sessions with terminal access | | `wsh` | Windows Subsystem for Host | Windows environment support | 资料来源：[clawteam/spawn/wsh_backend.py:1-50]() ## Step 1: Create a Team ### Spawn a New Team Create a team with a leader agent: ```bash clawteam team spawn-team [options] ``` | Option | Description | Default | |--------|-------------|---------| | `--description, -d` | Team description | `""` | | `--agent-name, -n` | Leader agent name | `"leader"` | | `--agent-type` | Leader agent type | `"leader"` | **Example:** ```bash clawteam team spawn-team dev-sprint -d "Backend development team" -n alice ``` The team leader will automatically be registered in the system. 资料来源：[skills/clawteam/references/cli-reference.md:100-115]() ### Verify Team Creation Check team status and members: ```bash clawteam team status ``` ### List Existing Teams Discover all teams in the network: ```bash clawteam team discover ``` Or get JSON output for scripting: ```bash clawteam --json team discover ``` Returns: name, description, leadAgentId, memberCount for each team. 资料来源：[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: ```bash clawteam spawn [options] ``` | Option | Description | Default | |--------|-------------|---------| | `--team, -t` | Team name | `"default"` | | `--agent-name, -n` | Agent name | auto-generated | | `--agent-type` | Agent type | `"general-purpose"` | **Example:** ```bash 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. 资料来源：[skills/clawteam/references/cli-reference.md:35-45]() ### Agent Identity Setup For spawned agents to operate within the team context, set identity environment variables: ```bash eval $(clawteam identity set --agent-name alice --team dev-team) ``` View current agent identity: ```bash clawteam identity show ``` 资料来源：[skills/clawteam/references/cli-reference.md:46-55]() ## Step 3: Manage Tasks ### Create a Task ```bash clawteam task create [options] ``` | Option | Description | Default | |--------|-------------|---------| | `--owner, -o` | Task owner | None | | `--description, -d` | Task description | None | | `--priority, -p` | Priority: low, medium, high, urgent | medium | | `--blocks` | Comma-separated task IDs this blocks | None | | `--blocked-by` | Comma-separated task IDs blocking this | None | **Example:** ```bash clawteam task create dev-team "Implement auth" -o alice -d "Add JWT authentication" ``` ### Update Task Status ```bash clawteam task update [options] ``` | Option | Description | |--------|-------------| | `--status, -s` | New status: pending, in_progress, completed, blocked | | `--owner, -o` | New owner | | `--add-blocks` | Task IDs to add to blocks | | `--add-blocked-by` | Task IDs to add to blocked-by | When a task is marked `completed`, any tasks blocked by it are automatically unblocked (moved from `blocked` to `pending` if no other blockers remain). 资料来源：[skills/clawteam/references/cli-reference.md:60-80]() ### List Team Tasks ```bash clawteam task list [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority] ``` ## Team Workflow Example ```mermaid 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: ```bash $ 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 ``` 资料来源：[website/src/App.jsx:1-60]() ## Lifecycle Management ### Request Agent Shutdown ```bash clawteam lifecycle request-shutdown [--reason TEXT] ``` ### Approve/Reject Shutdown ```bash clawteam lifecycle approve-shutdown clawteam lifecycle reject-shutdown [--reason TEXT] ``` ### Send Idle Notification When an agent has no more work: ```bash clawteam lifecycle idle [--last-task ID] [--task-status STATUS] ``` This notifies the team leader that the agent is available for new tasks. 资料来源：[skills/clawteam/references/cli-reference.md:130-150]() ## Communication Between Agents ### Message Types | Type | Description | |------|-------------| | `message` | General point-to-point message | | `broadcast` | Broadcast to all team members | | `join_request` | Request to join team | | `join_approved` / `join_rejected` | Join response | ### Send a Message ```bash clawteam message send ``` ### Join a Team Request to join an existing team: ```bash clawteam team request-join [options] ``` | Option | Description | Default | |--------|-------------|---------| | `--capabilities, -c` | Agent capabilities description | `""` | | `--timeout, -t` | Timeout in seconds | 60 | The leader can approve or reject the request: ```bash clawteam team approve-join [--assigned-name NAME] clawteam team reject-join ``` 资料来源：[skills/clawteam/references/cli-reference.md:25-30]() ## Plan Submission and Approval ### Submit a Plan ```bash clawteam plan submit [--summary TEXT] ``` ### Approve/Reject a Plan ```bash clawteam plan approve [--feedback TEXT] clawteam plan reject [--feedback TEXT] ``` 资料来源：[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 ```python # 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) ``` 资料来源：[clawteam/spawn/session_locators/claude.py:30-45]() ## Data Storage All team data is stored in `~/.clawteam/` by default: | Data Type | Storage Location | |-----------|------------------| | Teams | `~/.clawteam/teams/` | | Tasks | `~/.clawteam/teams//tasks/` | | Messages | `~/.clawteam/teams//inbox//` | | Sessions | `~/.clawteam/sessions/` | Task operations are backed by `FileTaskStore`: ```python from clawteam.store.base import BaseTaskStore, TaskLockError from clawteam.store.file import FileTaskStore TaskStore = FileTaskStore ``` 资料来源：[clawteam/team/tasks.py:1-20]() ## Next Steps - Review the [CLI Reference](skills/clawteam/references/cli-reference.md) for complete command documentation - Explore [Git-aware execution](skills/clawteam/SKILL.md) features for repository integration - Configure [runtime profiles](skills/clawteam/SKILL.md) for different agent environments --- ## System Architecture ### 相关页面 相关主题：[Introduction to ClawTeam](#page-introduction), [Transport Layer](#page-transport), [Event System](#page-event-system)
Relevant Source Files 以下源码文件用于生成本页说明： - [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py) - [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py) - [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py) - [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) - [skills/clawteam/SKILL.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/SKILL.md) - [website/src/App.jsx](https://github.com/HKUDS/ClawTeam/blob/main/website/src/App.jsx)
# 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. 资料来源：[skills/clawteam/SKILL.md:1-15]() ## High-Level Component Architecture ```mermaid 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. ```mermaid classDiagram class BaseTaskStore { <> +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** | Field | Type | Description | |-------|------|-------------| | `id` | string | Unique task identifier | | `subject` | string | Task title/summary | | `description` | string | Detailed task description | | `status` | enum | `pending`, `in_progress`, `completed`, `blocked` | | `owner` | string | Agent responsible for task | | `priority` | enum | `low`, `medium`, `high`, `urgent` | | `blocks` | list[string] | Task IDs this blocks | | `blocked_by` | list[string] | Task IDs blocking this | 资料来源：[clawteam/team/tasks.py:1-15]() **Task Status Transitions** | Current Status | Valid Transitions | Auto-Behavior | |----------------|-------------------|---------------| | `pending` | `in_progress`, `blocked` | - | | `in_progress` | `completed`, `blocked` | - | | `completed` | - | Unblocks all dependent tasks | | `blocked` | `pending`, `in_progress` | Auto-unblock when blockers complete | 资料来源：[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. ```mermaid 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** | Type | Direction | Purpose | |------|-----------|---------| | `message` | point-to-point | General communication between agents | | `broadcast` | one-to-all | Announcements to entire team | | `join_request` | worker→leader | Request to join team | | `join_approved` / `join_rejected` | leader→worker | Join response | | `plan_approval_request` | worker→leader | Submit plan for review | | `plan_approved` / `plan_rejected` | leader→worker | Plan response | | `shutdown_request` | any→any | Request agent shutdown | | `shutdown_approved` / `shutdown_rejected` | any→any | Shutdown response | | `idle` | worker→leader | Agent has no more work | 资料来源：[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** ```mermaid 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** | Option | Description | Default | |--------|-------------|---------| | `--team, -t` | Team name | `"default"` | | `--agent-name, -n` | Agent name | auto-generated | | `--agent-type` | Agent type | `"general-purpose"` | **Example Usage** ```bash clawteam spawn tmux claude --team dev-team --agent-name builder --agent-type researcher ``` 资料来源：[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. ```python 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 资料来源：[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** | Operation | Behavior | |-----------|----------| | `receive` | Destructive read - message removed after retrieval | | `peek` | Non-destructive read - message remains in inbox | ## Team Structure ```mermaid 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** | Command | Description | |---------|-------------| | `clawteam team spawn-team` | Create team and register leader | | `clawteam team discover` | List all existing teams | | `clawteam team status` | Show team configuration and members | | `clawteam team request-join` | Request to join a team | | `clawteam team approve-join` | Approve join request (leader only) | 资料来源：[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** | Role | Context Provided | |------|------------------| | `worker` | Sprint contract artifacts assigned to agent | | `evaluator` | Specification + all contract criteria | | `planner` | Spec draft for planning | ```python 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 ``` 资料来源：[clawteam/harness/context_recovery.py:1-75]() ## Frontend Architecture The website provides a browser-based dashboard for visualizing team state. ```mermaid 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 资料来源：[website/src/App.jsx:1-100]() ## Communication Flow ```mermaid 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 | Component | Dependencies | Purpose | |-----------|-------------|---------| | Task Store | `clawteam/store/base.py` | Abstract store interface | | Spawn Backends | `tmux`, `wsh` | Process management | | Event Bus | File system / P2P | Inter-agent messaging | | CLI | Click/Typer | Command parsing | | Context | Git worktrees | Repository awareness | 资料来源：[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. --- ## Event System ### 相关页面 相关主题：[System Architecture](#page-architecture), [Team Management](#page-team-management)
Relevant Source Files The following source files are listed as relevant for generating this page, but **were not present in the retrieved repository context**: - [clawteam/events/__init__.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/__init__.py) - [clawteam/events/bus.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/bus.py) - [clawteam/events/global_bus.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/global_bus.py) - [clawteam/events/types.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/types.py) - [clawteam/events/hooks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/hooks.py) The following files from the provided context were used to derive event-related information: - [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) - [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py) - [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)
# 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. 资料来源：[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. | Message Type | Description | |--------------|-------------| | `message` | General point-to-point message between agents | | `broadcast` | Broadcast message to all team members | | `join_request` | Request sent by an agent wanting to join the team | | `join_approved` / `join_rejected` | Response from team leader regarding join request | | `plan_approval_request` | Plan submitted by agent for leader review | | `plan_approved` / `plan_rejected` | Leader's decision on a submitted plan | | `shutdown_request` | Request to terminate an agent | | `shutdown_approved` / `shutdown_rejected` | Response to shutdown request | | `idle` | Notification sent when an agent has no more work | 资料来源：[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. | Status | Description | |--------|-------------| | `pending` | Task not yet started | | `in_progress` | Task currently being worked on | | `completed` | Task done — auto-unblocks dependent tasks | | `blocked` | Task waiting on other tasks to complete | When a task is marked `completed`, any tasks blocked by it are automatically unblocked (moved from `blocked` to `pending` if no other blockers remain). 资料来源：[skills/clawteam/references/cli-reference.md]() ## Inter-Agent Communication Flow ```mermaid 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
plan_rejected| A A -->|shutdown_request| E[Target Agent] E -->|shutdown_approved
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 ``` 资料来源：[skills/clawteam/references/cli-reference.md]() ### Board Show Command The `board show` command displays team board data with member-aware message aliases: ```bash clawteam board show clawteam --json board show ``` 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. 资料来源：[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: ```bash clawteam lifecycle idle [--last-task ID] [--task-status STATUS] ``` ### Shutdown Sequence ```bash # Request shutdown clawteam lifecycle request-shutdown [--reason TEXT] # Accept shutdown clawteam lifecycle approve-shutdown # Reject shutdown clawteam lifecycle reject-shutdown [--reason TEXT] ``` 资料来源：[skills/clawteam/references/cli-reference.md]() ## Plan Submission Events Agents submit plans for leader approval, creating an approval workflow: ```mermaid sequenceDiagram Agent->>Leader: plan submit Note over Leader: Reviews plan Leader->>Agent: plan approve Note over Agent: Plan approved, proceed with work ``` ### Plan Commands ```bash # Submit a plan clawteam plan submit [--summary TEXT] # Approve a plan clawteam plan approve [--feedback TEXT] # Reject a plan clawteam plan reject [--feedback TEXT] ``` 资料来源：[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: ```python 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() ``` 资料来源：[clawteam/harness/context_recovery.py:53-59]() Different roles receive different context: | Role | Context Provided | |------|------------------| | `executor` | Sprint contract artifact containing their assignment | | `evaluator` | Full spec.md content and all contract criteria | | `planner` | Spec draft content for planning purposes | 资料来源：[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: ```python 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. 资料来源：[clawteam/spawn/wsh_backend.py:52-61]() ## See Also - [CLI Reference](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) — Complete command documentation - [Task System](../team/tasks) — Task management and dependencies - [Spawn System](../spawn/index) — Agent spawning and backend management --- ## Agent Spawning System ### 相关页面 相关主题：[Quick Start Guide](#page-quickstart), [Team Management](#page-team-management)
相关源码文件 以下源码文件用于生成本页说明： - [clawteam/spawn/__init__.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/__init__.py) - [clawteam/spawn/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/base.py) - [clawteam/spawn/adapters.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/adapters.py) - [clawteam/spawn/tmux_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/tmux_backend.py) - [clawteam/spawn/subprocess_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/subprocess_backend.py) - [clawteam/spawn/profiles.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/profiles.py) - [clawteam/spawn/presets.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/presets.py) - [clawteam/spawn/prompt.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/prompt.py) - [clawteam/spawn/sessions.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/sessions.py) - [clawteam/spawn/session_locators/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_locators/base.py)
# 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. ```mermaid 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: | Backend | Description | Use Case | |---------|-------------|----------| | `subprocess` | Direct child process management | Simple single-agent scenarios | | `tmux` | Terminal multiplexer sessions | Persistent sessions with attach capability | | `wsh` | weish block isolation | Isolated workspace blocks | #### Base Backend Interface All backends implement a common interface defined in `base.py`: ```python 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 ``` 资料来源：[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: ```python 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), ) ``` 资料来源：[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 ```bash clawteam spawn [options] ``` ### Command Options | Option | Description | Default | |--------|-------------|---------| | `--team, -t` | Team name | `"default"` | | `--agent-name, -n` | Agent name | auto-generated | | `--agent-type` | Agent type | `"general-purpose"` | ### Example Usage ```bash # 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 ``` 资料来源：[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: ```bash export CLAWTEAM_AGENT_ID="" export CLAWTEAM_AGENT_NAME="" export CLAWTEAM_AGENT_TYPE="" export CLAWTEAM_TEAM_NAME="" ``` Agents can verify their identity using: ```bash clawteam identity show ``` 资料来源：[clawteam/cli/commands.py](), [skills/clawteam/references/cli-reference.md]() ## Session Management ### Session Persistence The system tracks agent sessions to enable resume functionality: ```python 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) ``` 资料来源：[clawteam/spawn/sessions.py](), [clawteam/spawn/session_capture.py]() ### Session Lifecycle ```mermaid 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: ```python 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 ``` 资料来源：[clawteam/spawn/session_locators/base.py]() ## Profile and Preset System ### Profiles Profiles are reusable configurations that define how agents should be spawned: ```bash # 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 ``` 资料来源：[clawteam/spawn/profiles.py](), [skills/clawteam/SKILL.md]() ### Presets Presets are provider templates used to generate profiles: | Preset | Provider | |--------|----------| | `moonshot-cn` | Moonshot CN | | `claude` | Anthropic Claude | | `openai` | OpenAI | | Custom | User-defined | ```bash # List presets clawteam preset list # Show preset details clawteam preset show moonshot-cn ``` 资料来源：[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: ```python 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, ) ``` 资料来源：[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/`: ```python 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" ``` 资料来源：[clawteam/cli/commands.py]() ### Supported Skill Formats - Directory format: `skills//SKILL.md` - Single file format: `skills/.md` ## Runtime Message Injection The system supports injecting runtime notifications into running agents: ```python 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) ``` 资料来源：[clawteam/spawn/wsh_backend.py](), [clawteam/spawn/base.py]() ## Team Template Launch For complex multi-agent scenarios, ClawTeam supports launching entire teams from templates: ```bash clawteam launch