{ "canonical_name": "HKUDS/ClawTeam", "compilation_id": "pack_0c0225ae06534074969a715fae9f60f5", "created_at": "2026-05-17T05:44:20.783872+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install clawteam` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install clawteam", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_699f7c19a079426ea190eecbcd877ad2" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_a8b73955f6aa380e7ef03998f94c732d", "canonical_name": "HKUDS/ClawTeam", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/HKUDS/ClawTeam", "slug": "clawteam", "source_packet_id": "phit_a1b6526e827542a0bd818f6d1bcb2b57", "source_validation_id": "dval_ba964ae4c6fe456582e7a5dbcfd8408e" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 claude的用户", "github_forks": null, "github_stars": null, "one_liner_en": "

\"\"  ClawTeam: Agent Swarm Intelligence

", "one_liner_zh": "

\"\"  ClawTeam: Agent Swarm Intelligence

", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, git" }, "target_user": "使用 claude, claude_code, cursor 等宿主 AI 的用户", "title_en": "ClawTeam", "title_zh": "ClawTeam 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Checkpoint Resume", "label_zh": "断点恢复流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-checkpoint-resume", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_a1b6526e827542a0bd818f6d1bcb2b57", "page_model": { "artifacts": { "artifact_slug": "clawteam", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install clawteam", "label": "Python / pip · 官方安装入口", "source": "https://github.com/HKUDS/ClawTeam#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "断点恢复流程", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 claude的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "

\"\"  ClawTeam: Agent Swarm Intelligence

" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "claude, claude_code, cursor, chatgpt", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_d8bd96f00b7c46c6813bc15c32a84625 | https://github.com/HKUDS/ClawTeam/issues/76 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | host_targets=claude, claude_code, cursor, chatgpt" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM plugin + reaction engine", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_114771b2a1474b358b05a6a9e61807f6 | https://github.com/HKUDS/ClawTeam/issues/157 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "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." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent Definitions Feature is Non-Functional: Parsed but Not Applied", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_dc9ad856da7a4a828860da94afadc7ec | https://github.com/HKUDS/ClawTeam/issues/146 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Agent Definitions Feature is Non-Functional: Parsed but Not Applied", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_61dec732a08f4279a590654f0eecea51 | https://github.com/HKUDS/ClawTeam/issues/104 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Worker agents exit after first turn despite 'ongoing job' task prompt", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_26124d52e6d948b2bf15809390ef2589 | https://github.com/HKUDS/ClawTeam/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Worker agents exit after first turn despite 'ongoing job' task prompt", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_63b04b7d23e74c71a8c1f8dddcaa9281 | https://github.com/HKUDS/ClawTeam/issues/45 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.0 — Stabilization Release", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_2aca0ffb17f94d8bb219737c9f275e7f | https://github.com/HKUDS/ClawTeam/releases/tag/v0.2.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.2.0 — Stabilization Release", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": null, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": null }, "source_url": "https://github.com/HKUDS/ClawTeam", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "

\"\"  ClawTeam: Agent Swarm Intelligence

", "title": "ClawTeam 能力包", "trial_prompt": "# ClawTeam - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for HKUDS/ClawTeam.\n\nProject:\n- Name: ClawTeam\n- Repository: https://github.com/HKUDS/ClawTeam\n- Summary:

\"\"  ClawTeam: Agent Swarm Intelligence

\n- Host target: claude, claude_code, cursor, chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet:

\"\"  ClawTeam: Agent Swarm Intelligence

\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to ClawTeam. Produce one small intermediate artifact and wait for confirmation.\n2. page-quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-agent-spawning: Agent Spawning System. Produce one small intermediate artifact and wait for confirmation.\n5. page-task-management: Task Management System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/HKUDS/ClawTeam#readme\n- .agents/skills/clawteam-dev/SKILL.md\n- .agents/skills/frontend-design/SKILL.md\n- docs/skills/clawteam/SKILL.md\n- skills/clawteam/SKILL.md\n- README.md\n- clawteam/__init__.py\n- clawteam/identity.py\n- pyproject.toml\n- scripts/install_clawteam.sh\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github, x。github/github_issue: Proposal: 8-PR sequence — canonical WorkerState, persistent event log, p（https://github.com/HKUDS/ClawTeam/issues/157）；github/github_issue: Security testing for multi-agent swarms: agent isolation, delegation tru（https://github.com/HKUDS/ClawTeam/issues/76）；github/github_issue: Agent Definitions Feature is Non-Functional: Parsed but Not Applied（https://github.com/HKUDS/ClawTeam/issues/146）；github/github_issue: Worker agents exit after first turn despite 'ongoing job' task prompt（https://github.com/HKUDS/ClawTeam/issues/148）；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（https://github.com/HKUDS/ClawTeam/issues/104）；github/github_release: v0.2.0 — Stabilization Release（https://github.com/HKUDS/ClawTeam/releases/tag/v0.2.0）；x: This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...（https://x.com/smratitiwa86867/status/2053078904131514835）；x: This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...（https://x.com/RamSingh_369/status/2053376331476500937）；x: This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...（https://x.com/RamSingh_369/status/2052615950047035852）；x: This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...（https://x.com/LearnWithBrij/status/2048309643060126180）；x: This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...（https://x.com/RamSingh_369/status/2053376331476500937/photo/1）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Proposal: 8-PR sequence — canonical WorkerState, persistent event log, p", "url": "https://github.com/HKUDS/ClawTeam/issues/157" }, { "kind": "github_issue", "source": "github", "title": "Security testing for multi-agent swarms: agent isolation, delegation tru", "url": "https://github.com/HKUDS/ClawTeam/issues/76" }, { "kind": "github_issue", "source": "github", "title": "Agent Definitions Feature is Non-Functional: Parsed but Not Applied", "url": "https://github.com/HKUDS/ClawTeam/issues/146" }, { "kind": "github_issue", "source": "github", "title": "Worker agents exit after first turn despite 'ongoing job' task prompt", "url": "https://github.com/HKUDS/ClawTeam/issues/148" }, { "kind": "github_issue", "source": "github", "title": "[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC", "url": "https://github.com/HKUDS/ClawTeam/issues/45" }, { "kind": "github_issue", "source": "github", "title": "High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetc", "url": "https://github.com/HKUDS/ClawTeam/issues/104" }, { "kind": "github_release", "source": "github", "title": "v0.2.0 — Stabilization Release", "url": "https://github.com/HKUDS/ClawTeam/releases/tag/v0.2.0" }, { "kind": "searxng_indexed", "source": "x", "title": "This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...", "url": "https://x.com/smratitiwa86867/status/2053078904131514835" }, { "kind": "searxng_indexed", "source": "x", "title": "This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...", "url": "https://x.com/RamSingh_369/status/2053376331476500937" }, { "kind": "searxng_indexed", "source": "x", "title": "This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...", "url": "https://x.com/RamSingh_369/status/2052615950047035852" }, { "kind": "searxng_indexed", "source": "x", "title": "This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...", "url": "https://x.com/LearnWithBrij/status/2048309643060126180" }, { "kind": "searxng_indexed", "source": "x", "title": "This is the Claude Code Resource Bible. 54 tools. Agents. MCP ...", "url": "https://x.com/RamSingh_369/status/2053376331476500937/photo/1" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "

\"\"  ClawTeam: Agent Swarm Intelligence

", "effort": "安装已验证", "forks": null, "icon": "code", "name": "ClawTeam 能力包", "risk": "可发布", "slug": "clawteam", "stars": null, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "断点恢复流程", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/HKUDS/ClawTeam 项目说明书\n\n生成时间：2026-05-17 05:40:48 UTC\n\n## 目录\n\n- [Introduction to ClawTeam](#page-introduction)\n- [Quick Start Guide](#page-quickstart)\n- [System Architecture](#page-architecture)\n- [Event System](#page-event-system)\n- [Agent Spawning System](#page-agent-spawning)\n- [Task Management System](#page-task-management)\n- [Team Management](#page-team-management)\n- [Transport Layer](#page-transport)\n- [Messaging & Inbox System](#page-messaging)\n- [Board & Monitoring Dashboard](#page-board-dashboard)\n\n\n\n## Introduction to ClawTeam\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [website/src/App.jsx](https://github.com/HKUDS/ClawTeam/blob/main/website/src/App.jsx)\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [skills/clawteam/SKILL.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/SKILL.md)\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)\n- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n- [clawteam/spawn/session_locators/claude.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_locators/claude.py)\n
\n\n# Introduction to ClawTeam\n\nClawTeam 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.\n\n## Purpose and Scope\n\nClawTeam addresses a fundamental limitation in modern AI-assisted development: isolated agent sessions working independently without coordination. The platform provides:\n\n- **Team Management**: Create and manage teams of agents with designated leaders\n- **Task Coordination**: Shared task boards with dependency tracking and priority levels\n- **Inter-Agent Communication**: File-based inbox system for point-to-point and broadcast messaging\n- **Session Management**: Spawn, monitor, and lifecycle control of agent processes\n- **Context Injection**: Git-aware context tools for worktree isolation and overlap detection\n\n资料来源：[skills/clawteam/SKILL.md]()\n\n## Architecture Overview\n\nClawTeam follows a leader-worker architecture where one agent serves as the coordinator while others perform specialized tasks.\n\n```mermaid\ngraph TD\n A[Leader Agent] --> B[Worker Agent 1]\n A --> C[Worker Agent 2]\n A --> D[Worker Agent N]\n B --> E[Task Store]\n C --> E\n D --> E\n A --> F[Message Inboxes]\n B --> F\n C --> F\n D --> F\n G[CLI Interface] --> A\n G --> H[Board Dashboard]\n```\n\n### Core Components\n\n| Component | Description |\n|-----------|-------------|\n| **CLI Interface** | Command-line entry point for all operations |\n| **Team Manager** | Handles team creation, membership, and discovery |\n| **Task Store** | File-based task board with dependency chains |\n| **Message Inbox** | Per-agent file-based message queue |\n| **Spawn Backends** | tmux, subprocess, wsh for launching agents |\n| **Session Locators** | Detects and captures existing agent sessions |\n\n资料来源：[clawteam/team/tasks.py:1-12]()\n\n## Data Storage Model\n\nAll data is persisted in `~/.clawteam/` with a structured directory layout:\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # TeamConfig (name, members, leader)\n│ └── inboxes/{agent}/ # msg-{timestamp}-{uuid}.json files\n├── tasks/{team}/\n│ └── task-{id}.json # Individual task files\n└── plans/\n └── {agent}-{id}.md # Plan documents\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Task Management System\n\nTasks form the backbone of team coordination, supporting four distinct statuses:\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Not yet started |\n| `in_progress` | Currently being worked on |\n| `completed` | Done (auto-unblocks dependents) |\n| `blocked` | Waiting on other tasks |\n\n### Task Dependencies\n\nTasks support dependency chains through two parameters:\n\n- `--blocks`: Task IDs this task blocks upon completion\n- `--blocked-by`: Task IDs blocking this task from starting\n\nWhen a task is marked `completed`, any tasks blocked by it are automatically unblocked (moved from `blocked` to `pending` if no other blockers remain).\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n```mermaid\ngraph LR\n T1[Task 1: Design] --> T2[Task 2: Implement]\n T2 --> T3[Task 3: Test]\n T3 --> T4[Task 4: Deploy]\n T1 -->|blocks| T2\n T2 -->|blocks| T3\n T3 -->|blocks| T4\n```\n\n## Message Types\n\nThe inbox system supports various message types for inter-agent communication:\n\n| Type | Description |\n|------|-------------|\n| `message` | General point-to-point message |\n| `broadcast` | Broadcast to all members |\n| `join_request` | Request to join team |\n| `join_approved` / `join_rejected` | Join response |\n| `plan_approval_request` | Plan submitted for review |\n| `plan_approved` / `plan_rejected` | Plan response |\n| `shutdown_request` | Shutdown request |\n| `shutdown_approved` / `shutdown_rejected` | Shutdown response |\n| `idle` | Agent idle notification |\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Spawn Backends\n\nClawTeam supports multiple spawn backends for launching agents:\n\n| Backend | Description |\n|---------|-------------|\n| `tmux` | Default backend, sessions in tmux panes |\n| `subprocess` | Direct subprocess spawning |\n| `wsh` | WebSocket handler for IDE integration |\n\nThe spawn command configures team environment variables for spawned agents:\n\n```bash\nclawteam spawn [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--team, -t` | Team name | `\"default\"` |\n| `--agent-name, -n` | Agent name | auto-generated |\n| `--agent-type` | Agent type | `\"general-purpose\"` |\n\n资料来源：[clawteam/spawn/wsh_backend.py:1-30]()\n\n## Session Management\n\nFor Claude Code specifically, ClawTeam integrates with existing sessions:\n\n```python\n# Session capture flow from clawteam/spawn/session_locators/claude.py\nsession_id = str(uuid.uuid4())\nreturn PreparedSession(\n command=[*command, \"--session-id\", session_id],\n client=self.client,\n session_id=session_id,\n source=\"generated\",\n confidence=\"exact\",\n cwd=context.cwd,\n)\n```\n\nThe system can detect existing sessions via:\n- Environment variables (`CLAUDE_CODE_SESSION`, `CLAUDE_SESSION_ID`)\n- Project directory session files (`.jsonl` format)\n\n资料来源：[clawteam/spawn/session_locators/claude.py:1-60]()\n\n## Lifecycle Management\n\nAgents support a complete lifecycle for graceful shutdown:\n\n```mermaid\ngraph TD\n A[Agent Running] --> B{Shutdown Request}\n B -->|approve| C[Agent Shuts Down]\n B -->|reject| D[Agent Continues]\n A --> E[Idle Notification]\n E --> F[Leader Reassigns Tasks]\n```\n\n### Lifecycle Commands\n\n| Command | Purpose |\n|---------|---------|\n| `lifecycle request-shutdown` | Request an agent to shut down |\n| `lifecycle approve-shutdown` | Agent agrees to shut down |\n| `lifecycle reject-shutdown` | Agent rejects shutdown request |\n| `lifecycle idle` | Send idle notification to leader |\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Quick Start\n\n### Installation\n\n```bash\nclawteam --version # Check if installed\npip install clawteam # Requires Python 3.10+\n```\n\n### Create and Manage a Team\n\n```bash\n# Set agent identity\nexport CLAWTEAM_AGENT_ID=\"leader-001\"\nexport CLAWTEAM_AGENT_NAME=\"leader\"\nexport CLAWTEAM_AGENT_TYPE=\"leader\"\n\n# Spawn a team with leader\nclawteam team spawn-team my-team -d \"Project team\" -n leader\n\n# Create tasks\nclawteam task create my-team \"Design system\" -o leader\nclawteam task create my-team \"Implement feature\" -o worker1\nclawteam task create my-team \"Write tests\" -o worker2\n\n# View team board\nclawteam board show my-team\n```\n\n### Spawn Worker Agents\n\n```bash\nclawteam spawn tmux claude-code --team my-team --agent-name builder\nclawteam spawn tmux claude-code --team my-team --agent-name reviewer\n```\n\n资料来源：[skills/clawteam/SKILL.md]()\n\n## Board Dashboard\n\nThe board command provides team visibility through multiple views:\n\n| Command | Description |\n|---------|-------------|\n| `board show` | Detailed kanban board with message history |\n| `board overview` | Summary of all teams in table format |\n| `board live` | Live-refreshing kanban board with auto-refresh |\n\n```bash\n# JSON output for integration\nclawteam --json board show my-team\n\n# Live monitoring\nclawteam board live my-team --interval 2.0\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Identity System\n\nEach agent requires environment variables for identification within the team:\n\n```bash\neval $(clawteam identity set --agent-name alice --team dev-team)\n```\n\nThe identity system exposes:\n- `CLAWTEAM_AGENT_ID`: Unique identifier\n- `CLAWTEAM_AGENT_NAME`: Human-readable name\n- `CLAWTEAM_AGENT_TYPE`: Role classification (leader, general-purpose, etc.)\n\n资料来源：[clawteam/harness/context_recovery.py:1-40]()\n\n## Context Recovery\n\nThe harness system provides role-based context recovery for agents:\n\n```python\n# Layer 5: One-liner teammate summaries from context_recovery.py\ndef _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:\n from clawteam.team.tasks import TaskStore\n store = TaskStore(team_name)\n tasks = store.list_tasks()\n # Group by owner, exclude self\n owner_status: dict[str, tuple[int, int]] = {}\n```\n\nThis enables leaders to understand team workload distribution and assign tasks appropriately.\n\n资料来源：[clawteam/harness/context_recovery.py:40-70]()\n\n## See Also\n\n- [CLI Reference](skills/clawteam/references/cli-reference.md) - Complete command documentation\n- [SKILL.md](skills/clawteam/SKILL.md) - Comprehensive usage guide\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to ClawTeam](#page-introduction), [Agent Spawning System](#page-agent-spawning)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/HKUDS/ClawTeam/blob/main/README.md)\n- [pyproject.toml](https://github.com/HKUDS/ClawTeam/blob/main/pyproject.toml)\n- [skills/clawteam/SKILL.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/SKILL.md)\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [clawteam/spawn/session_locators/claude.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_locators/claude.py)\n- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)\n
\n\n# Quick Start Guide\n\nClawTeam 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.\n\n## Prerequisites\n\nBefore getting started with ClawTeam, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details | Notes |\n|-------------|-----------------|-------|\n| Python | 3.10+ | Required runtime |\n| tmux | Latest | Default spawn backend |\n| Git | Any recent version | For worktree isolation and context features |\n| Coding Agent CLI | Claude, Codex, Gemini, etc. | At least one agent client installed |\n\n资料来源：[skills/clawteam/SKILL.md:20-30]()\n\n## Installation\n\n### Standard Installation\n\nInstall ClawTeam via pip:\n\n```bash\npip install clawteam\n```\n\n### Installation with P2P Transport Support\n\nFor peer-to-peer transport capabilities:\n\n```bash\npip install \"clawteam[p2p]\"\n```\n\n### Verify Installation\n\nConfirm ClawTeam is installed correctly:\n\n```bash\nclawteam --version\n```\n\n资料来源：[skills/clawteam/SKILL.md:12-18]()\n\n## Core Concepts\n\nUnderstanding these fundamental concepts is essential before creating your first agent team.\n\n### Teams\n\nTeams 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]()\n\n### Tasks\n\nShared task board with status tracking:\n- `pending` — Not yet started\n- `in_progress` — Currently being worked on\n- `completed` — Done; auto-unblocks dependent tasks\n- `blocked` — Waiting on other tasks to complete\n\nTasks support dependency chains and priority levels (low, medium, high, urgent). 资料来源：[skills/clawteam/references/cli-reference.md:80-88]()\n\n### Inbox\n\nFile-based message queue per agent. Messages can be destructive (`receive`) or non-destructive (`peek`). 资料来源：[skills/clawteam/SKILL.md:34]()\n\n### Spawn Backends\n\nClawTeam supports multiple agent spawning backends:\n\n| Backend | Description | Use Case |\n|---------|-------------|----------|\n| `subprocess` | Spawns agent as subprocess | Simple local execution |\n| `tmux` | Spawns agent in tmux session | Persistent sessions with terminal access |\n| `wsh` | Windows Subsystem for Host | Windows environment support |\n\n资料来源：[clawteam/spawn/wsh_backend.py:1-50]()\n\n## Step 1: Create a Team\n\n### Spawn a New Team\n\nCreate a team with a leader agent:\n\n```bash\nclawteam team spawn-team [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--description, -d` | Team description | `\"\"` |\n| `--agent-name, -n` | Leader agent name | `\"leader\"` |\n| `--agent-type` | Leader agent type | `\"leader\"` |\n\n**Example:**\n\n```bash\nclawteam team spawn-team dev-sprint -d \"Backend development team\" -n alice\n```\n\nThe team leader will automatically be registered in the system. 资料来源：[skills/clawteam/references/cli-reference.md:100-115]()\n\n### Verify Team Creation\n\nCheck team status and members:\n\n```bash\nclawteam team status \n```\n\n### List Existing Teams\n\nDiscover all teams in the network:\n\n```bash\nclawteam team discover\n```\n\nOr get JSON output for scripting:\n\n```bash\nclawteam --json team discover\n```\n\nReturns: name, description, leadAgentId, memberCount for each team. 资料来源：[skills/clawteam/references/cli-reference.md:116-120]()\n\n## Step 2: Spawn Agents\n\n### Spawn an Agent into a Team\n\nAdd a worker agent to your team:\n\n```bash\nclawteam spawn [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--team, -t` | Team name | `\"default\"` |\n| `--agent-name, -n` | Agent name | auto-generated |\n| `--agent-type` | Agent type | `\"general-purpose\"` |\n\n**Example:**\n\n```bash\nclawteam spawn tmux claude --team dev-sprint --agent-name builder --agent-type researcher\n```\n\nThis 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]()\n\n### Agent Identity Setup\n\nFor spawned agents to operate within the team context, set identity environment variables:\n\n```bash\neval $(clawteam identity set --agent-name alice --team dev-team)\n```\n\nView current agent identity:\n\n```bash\nclawteam identity show\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:46-55]()\n\n## Step 3: Manage Tasks\n\n### Create a Task\n\n```bash\nclawteam task create [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--owner, -o` | Task owner | None |\n| `--description, -d` | Task description | None |\n| `--priority, -p` | Priority: low, medium, high, urgent | medium |\n| `--blocks` | Comma-separated task IDs this blocks | None |\n| `--blocked-by` | Comma-separated task IDs blocking this | None |\n\n**Example:**\n\n```bash\nclawteam task create dev-team \"Implement auth\" -o alice -d \"Add JWT authentication\"\n```\n\n### Update Task Status\n\n```bash\nclawteam task update [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `--status, -s` | New status: pending, in_progress, completed, blocked |\n| `--owner, -o` | New owner |\n| `--add-blocks` | Task IDs to add to blocks |\n| `--add-blocked-by` | Task IDs to add to blocked-by |\n\nWhen 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]()\n\n### List Team Tasks\n\n```bash\nclawteam task list [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]\n```\n\n## Team Workflow Example\n\n```mermaid\ngraph TD\n A[Install ClawTeam] --> B[Spawn Team with Leader]\n B --> C[Leader Creates Initial Tasks]\n C --> D[Spawn Worker Agents]\n D --> E[Workers Pick Tasks]\n E --> F[Complete Task]\n F --> G{Tasks Blocked?}\n G -->|Yes| H[Wait for Blockers]\n G -->|No| I[Mark Complete]\n H --> I\n I --> J{More Tasks?}\n J -->|Yes| E\n J -->|No| K[Idle Notification]\n```\n\n### Terminal Workflow Demo\n\nThe following demonstrates the typical CLI workflow:\n\n```bash\n$ clawteam team spawn-team docs-sprint\n✓ Team \"docs-sprint\" created\n\n$ clawteam spawn tmux claude-code --agent-name builder\n✓ Agent \"builder\" spawned in tmux\n\n$ clawteam team status docs-sprint\ndocs-sprint 3 agents active\n● T-001 Build landing page done\n● T-002 Write API docs active\n○ T-003 Review & merge blocked\n```\n\n资料来源：[website/src/App.jsx:1-60]()\n\n## Lifecycle Management\n\n### Request Agent Shutdown\n\n```bash\nclawteam lifecycle request-shutdown [--reason TEXT]\n```\n\n### Approve/Reject Shutdown\n\n```bash\nclawteam lifecycle approve-shutdown \nclawteam lifecycle reject-shutdown [--reason TEXT]\n```\n\n### Send Idle Notification\n\nWhen an agent has no more work:\n\n```bash\nclawteam lifecycle idle [--last-task ID] [--task-status STATUS]\n```\n\nThis notifies the team leader that the agent is available for new tasks. 资料来源：[skills/clawteam/references/cli-reference.md:130-150]()\n\n## Communication Between Agents\n\n### Message Types\n\n| Type | Description |\n|------|-------------|\n| `message` | General point-to-point message |\n| `broadcast` | Broadcast to all team members |\n| `join_request` | Request to join team |\n| `join_approved` / `join_rejected` | Join response |\n\n### Send a Message\n\n```bash\nclawteam message send \n```\n\n### Join a Team\n\nRequest to join an existing team:\n\n```bash\nclawteam team request-join [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--capabilities, -c` | Agent capabilities description | `\"\"` |\n| `--timeout, -t` | Timeout in seconds | 60 |\n\nThe leader can approve or reject the request:\n\n```bash\nclawteam team approve-join [--assigned-name NAME]\nclawteam team reject-join \n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:25-30]()\n\n## Plan Submission and Approval\n\n### Submit a Plan\n\n```bash\nclawteam plan submit [--summary TEXT]\n```\n\n### Approve/Reject a Plan\n\n```bash\nclawteam plan approve [--feedback TEXT]\nclawteam plan reject [--feedback TEXT]\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:95-108]()\n\n## Session Persistence\n\nClawTeam handles session persistence for agents like Claude Code. When spawning an agent:\n\n1. If `--continue` or `-c` flag is used, the agent continues from its last session\n2. Otherwise, a new session ID is generated automatically\n3. Session state is captured and stored for future restoration\n\n```python\n# Session capture flow\nif prepared.session_id:\n return CapturedSession(\n session_id=prepared.session_id,\n client=self.client,\n source=prepared.source or \"prepared\",\n confidence=prepared.confidence or \"exact\",\n cwd=context.cwd,\n )\nreturn self.current_session(context)\n```\n\n资料来源：[clawteam/spawn/session_locators/claude.py:30-45]()\n\n## Data Storage\n\nAll team data is stored in `~/.clawteam/` by default:\n\n| Data Type | Storage Location |\n|-----------|------------------|\n| Teams | `~/.clawteam/teams/` |\n| Tasks | `~/.clawteam/teams//tasks/` |\n| Messages | `~/.clawteam/teams//inbox//` |\n| Sessions | `~/.clawteam/sessions/` |\n\nTask operations are backed by `FileTaskStore`:\n\n```python\nfrom clawteam.store.base import BaseTaskStore, TaskLockError\nfrom clawteam.store.file import FileTaskStore\n\nTaskStore = FileTaskStore\n```\n\n资料来源：[clawteam/team/tasks.py:1-20]()\n\n## Next Steps\n\n- Review the [CLI Reference](skills/clawteam/references/cli-reference.md) for complete command documentation\n- Explore [Git-aware execution](skills/clawteam/SKILL.md) features for repository integration\n- Configure [runtime profiles](skills/clawteam/SKILL.md) for different agent environments\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to ClawTeam](#page-introduction), [Transport Layer](#page-transport), [Event System](#page-event-system)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [skills/clawteam/SKILL.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/SKILL.md)\n- [website/src/App.jsx](https://github.com/HKUDS/ClawTeam/blob/main/website/src/App.jsx)\n
\n\n# System Architecture\n\n## Overview\n\nClawTeam 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.\n\nThe 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.\n\n资料来源：[skills/clawteam/SKILL.md:1-15]()\n\n## High-Level Component Architecture\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[clawteam CLI]\n end\n \n subgraph \"Core Services\"\n TM[Team Manager]\n TS[Task Store]\n EB[Event Bus]\n TR[Transport Layer]\n end\n \n subgraph \"Spawn Backends\"\n TMUX[Tmux Backend]\n WSH[Wsh Backend]\n SUB[Subprocess Backend]\n end\n \n subgraph \"Agent Runtime\"\n AG1[Agent 1]\n AG2[Agent 2]\n AGn[Agent N]\n end\n \n subgraph \"Data Storage\"\n ST[Store - FileSystem]\n IN[Inbox - per-agent]\n TK[Tasks JSON]\n PL[Plan Files]\n end\n \n CLI --> TM\n CLI --> TS\n CLI --> EB\n CLI --> TR\n TM --> TS\n TM --> EB\n EB --> TR\n TR --> AG1\n TR --> AG2\n AG1 --> ST\n AG2 --> ST\n ST --> IN\n ST --> TK\n ST --> PL\n```\n\n## Core Modules\n\n### Task Store Layer\n\nThe 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.\n\n```mermaid\nclassDiagram\n class BaseTaskStore {\n <>\n +create_task(task) Task\n +get_task(task_id) Task\n +update_task(task_id, updates) Task\n +list_tasks() List~Task~\n +delete_task(task_id)\n +acquire_lock(task_id) ContextManager\n +release_lock(task_id)\n }\n \n class FileTaskStore {\n +_base_path: Path\n +create_task(task) Task\n +get_task(task_id) Task\n +update_task(task_id, updates) Task\n +list_tasks() List~Task~\n }\n \n class TaskLockError {\n +Exception\n }\n \n BaseTaskStore <|-- FileTaskStore\n BaseTaskStore -- TaskLockError\n```\n\n**Task Data Model**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Unique task identifier |\n| `subject` | string | Task title/summary |\n| `description` | string | Detailed task description |\n| `status` | enum | `pending`, `in_progress`, `completed`, `blocked` |\n| `owner` | string | Agent responsible for task |\n| `priority` | enum | `low`, `medium`, `high`, `urgent` |\n| `blocks` | list[string] | Task IDs this blocks |\n| `blocked_by` | list[string] | Task IDs blocking this |\n\n资料来源：[clawteam/team/tasks.py:1-15]()\n\n**Task Status Transitions**\n\n| Current Status | Valid Transitions | Auto-Behavior |\n|----------------|-------------------|---------------|\n| `pending` | `in_progress`, `blocked` | - |\n| `in_progress` | `completed`, `blocked` | - |\n| `completed` | - | Unblocks all dependent tasks |\n| `blocked` | `pending`, `in_progress` | Auto-unblock when blockers complete |\n\n资料来源：[skills/clawteam/references/cli-reference.md:85-100]()\n\n### Event Bus\n\nThe event system enables inter-agent communication through a pub-sub pattern. Events flow through the transport layer to reach individual agent inboxes.\n\n```mermaid\ngraph LR\n A[Agent A] -->|publish| EB[Event Bus]\n EB -->|deliver| IN1[Inbox A]\n EB -->|deliver| IN2[Inbox B]\n EB -->|deliver| INn[Inbox N]\n \n subgraph \"Message Types\"\n MSG[message]\n BC[broadcast]\n JR[join_request]\n PA[plan_approval_request]\n SR[shutdown_request]\n IDL[idle]\n end\n \n EB -.->|routes| MSG\n EB -.->|routes| BC\n EB -.->|routes| JR\n EB -.->|routes| PA\n EB -.->|routes| SR\n EB -.->|routes| IDL\n```\n\n**Supported Message Types**\n\n| Type | Direction | Purpose |\n|------|-----------|---------|\n| `message` | point-to-point | General communication between agents |\n| `broadcast` | one-to-all | Announcements to entire team |\n| `join_request` | worker→leader | Request to join team |\n| `join_approved` / `join_rejected` | leader→worker | Join response |\n| `plan_approval_request` | worker→leader | Submit plan for review |\n| `plan_approved` / `plan_rejected` | leader→worker | Plan response |\n| `shutdown_request` | any→any | Request agent shutdown |\n| `shutdown_approved` / `shutdown_rejected` | any→any | Shutdown response |\n| `idle` | worker→leader | Agent has no more work |\n\n资料来源：[skills/clawteam/references/cli-reference.md:110-125]()\n\n### Spawn Backend System\n\nThe spawn system launches agent processes using configurable backends. Each backend implements a common interface for process management and runtime injection.\n\n**Backend Architecture**\n\n```mermaid\ngraph TD\n subgraph \"Spawn Factory\"\n SF[Backend Factory]\n end\n \n SF --> TMUX[Tmux Backend]\n SF --> WSH[Wsh Backend]\n SF --> SUB[Subprocess Backend]\n \n subgraph \"Agent Lifecycle\"\n LAUNCH[Launch]\n MONITOR[Monitor]\n INJECT[Inject Runtime]\n TERMINATE[Terminate]\n end\n \n TMUX --> LAUNCH\n WSH --> LAUNCH\n SUB --> LAUNCH\n TMUX --> MONITOR\n WSH --> MONITOR\n SUB --> MONITOR\n WSH --> INJECT\n TMUX --> INJECT\n SUB --> INJECT\n```\n\n**Spawn Command Parameters**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--team, -t` | Team name | `\"default\"` |\n| `--agent-name, -n` | Agent name | auto-generated |\n| `--agent-type` | Agent type | `\"general-purpose\"` |\n\n**Example Usage**\n\n```bash\nclawteam spawn tmux claude --team dev-team --agent-name builder --agent-type researcher\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:25-45]()\n\n### Wsh Backend Implementation\n\nThe WebSocket-based spawn backend (`wsh_backend.py`) provides runtime message injection into running agent sessions.\n\n```python\ndef inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n \"\"\"Best-effort runtime injection into a running wsh block.\"\"\"\n from clawteam.spawn.registry import get_registry\n\n info = get_registry(team).get(agent_name, {})\n block_id = info.get(\"block_id\", \"\") or self._blocks.get(agent_name, \"\")\n if not block_id:\n return False, f\"wsh block for '{team}/{agent_name}' not found\"\n if not _is_block_alive(block_id):\n return False, f\"wsh block '{block_id}' is not alive\"\n # ... RPC client payload delivery\n```\n\n**Agent Registration Flow**\n\n1. Agent spawns with `team_name`, `agent_name`, `backend` type\n2. Backend calls `register_agent()` with metadata\n3. Spawn data persisted via `persist_spawned_session()`\n4. Agent entry stored in registry for runtime lookups\n\n资料来源：[clawteam/spawn/wsh_backend.py:1-55]()\n\n## Data Storage Layout\n\nAll persistent data resides under `~/.clawteam/` with a structured directory hierarchy:\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # TeamConfig (name, members, leader)\n│ └── inboxes/{agent}/ # msg-{timestamp}-{uuid}.json files\n├── tasks/{team}/\n│ └── task-{id}.json # Individual task files\n└── plans/\n └── {agent}-{id}.md # Plan documents\n```\n\n**Inbox Operations**\n\n| Operation | Behavior |\n|-----------|----------|\n| `receive` | Destructive read - message removed after retrieval |\n| `peek` | Non-destructive read - message remains in inbox |\n\n## Team Structure\n\n```mermaid\ngraph TD\n subgraph \"Team: dev-team\"\n L[Leader Agent]\n W1[Worker: alice]\n W2[Worker: bob]\n W3[Worker: charlie]\n \n L -->|manages| W1\n L -->|manages| W2\n L -->|manages| W3\n \n subgraph \"Shared Resources\"\n TB[Task Board]\n CH[Inbox Channel]\n CT[Context]\n end\n \n W1 --> TB\n W2 --> TB\n W3 --> TB\n W1 --> CH\n W2 --> CH\n W3 --> CH\n end\n```\n\n**Team Commands**\n\n| Command | Description |\n|---------|-------------|\n| `clawteam team spawn-team` | Create team and register leader |\n| `clawteam team discover` | List all existing teams |\n| `clawteam team status` | Show team configuration and members |\n| `clawteam team request-join` | Request to join a team |\n| `clawteam team approve-join` | Approve join request (leader only) |\n\n资料来源：[skills/clawteam/references/cli-reference.md:130-160]()\n\n## Context and Recovery System\n\nThe context recovery module provides role-specific context injection for agents operating within the harness system.\n\n**Role-Based Context Layers**\n\n| Role | Context Provided |\n|------|------------------|\n| `worker` | Sprint contract artifacts assigned to agent |\n| `evaluator` | Specification + all contract criteria |\n| `planner` | Spec draft for planning |\n\n```python\ndef _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:\n \"\"\"Layer 5: One-liner teammate summaries.\"\"\"\n try:\n from clawteam.team.tasks import TaskStore\n store = TaskStore(team_name)\n tasks = store.list_tasks()\n\n # Group by owner, exclude self\n owner_status: dict[str, tuple[int, int]] = {}\n for t in tasks:\n if t.owner and t.owner != agent_name:\n done, total = owner_status.get(t.owner, (0, 0))\n total += 1\n if t.status == TaskStatus.COMPLETED:\n done += 1\n owner_status[t.owner] = (done, total)\n except Exception:\n pass\n```\n\n资料来源：[clawteam/harness/context_recovery.py:1-75]()\n\n## Frontend Architecture\n\nThe website provides a browser-based dashboard for visualizing team state.\n\n```mermaid\ngraph LR\n subgraph \"React Components\"\n App[App.jsx]\n TM[TerminalMockup]\n HG[HalfGlobe]\n end\n \n subgraph \"UI Sections\"\n H[Hero]\n F[Features]\n W[Workflow]\n D[Docs]\n end\n \n subgraph \"Data Display\"\n TL[Terminal Output]\n KB[Kanban Board]\n ST[Status Grid]\n end\n \n App --> TM\n App --> HG\n TM --> TL\n H --> KB\n F --> ST\n W --> D\n```\n\n**Terminal Mockup Features**\n\n- Real-time team status display\n- Agent spawn simulation\n- Task progress visualization with status badges\n- Animated cursor for active states\n\n资料来源：[website/src/App.jsx:1-100]()\n\n## Communication Flow\n\n```mermaid\nsequenceDiagram\n participant L as Leader\n participant W1 as Worker Alice\n participant W2 as Worker Bob\n participant T as TaskStore\n participant I as Inbox\n \n W1->>L: request-join(team, \"alice\")\n L->>T: create_task()\n L->>W1: join_approved\n W1->>T: update_task(status=in_progress)\n W1->>L: plan_approval_request\n L->>W1: plan_approved\n W1->>T: update_task(status=completed)\n T->>W2: unblock(task_id)\n W2->>L: idle(last_task=T-001)\n```\n\n## Key Dependencies\n\n| Component | Dependencies | Purpose |\n|-----------|-------------|---------|\n| Task Store | `clawteam/store/base.py` | Abstract store interface |\n| Spawn Backends | `tmux`, `wsh` | Process management |\n| Event Bus | File system / P2P | Inter-agent messaging |\n| CLI | Click/Typer | Command parsing |\n| Context | Git worktrees | Repository awareness |\n\n资料来源：[skills/clawteam/SKILL.md:1-40]()\n\n## Summary\n\nClawTeam's architecture centers on three pillars:\n\n1. **Team Coordination** - Leader-based hierarchy with worker registration and task distribution\n2. **Persistent Storage** - File-based task boards, inboxes, and plans under `~/.clawteam/`\n3. **Flexible Spawning** - Pluggable backends (tmux, subprocess, wsh) for agent lifecycle management\n\nThe system is designed for git-aware, multi-agent development workflows where agents share task context, communicate via typed messages, and maintain independent worktree isolation.\n\n---\n\n\n\n## Event System\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Team Management](#page-team-management)\n\n
\nRelevant Source Files\n\nThe following source files are listed as relevant for generating this page, but **were not present in the retrieved repository context**:\n\n- [clawteam/events/__init__.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/__init__.py)\n- [clawteam/events/bus.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/bus.py)\n- [clawteam/events/global_bus.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/global_bus.py)\n- [clawteam/events/types.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/types.py)\n- [clawteam/events/hooks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/events/hooks.py)\n\nThe following files from the provided context were used to derive event-related information:\n\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n\n
\n\n# Event System\n\n> ⚠️ **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.\n\n## Overview\n\nThe 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.\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Message Types\n\nThe system defines several message/event types that flow between team members. These types represent the different categories of communication that agents use to coordinate.\n\n| Message Type | Description |\n|--------------|-------------|\n| `message` | General point-to-point message between agents |\n| `broadcast` | Broadcast message to all team members |\n| `join_request` | Request sent by an agent wanting to join the team |\n| `join_approved` / `join_rejected` | Response from team leader regarding join request |\n| `plan_approval_request` | Plan submitted by agent for leader review |\n| `plan_approved` / `plan_rejected` | Leader's decision on a submitted plan |\n| `shutdown_request` | Request to terminate an agent |\n| `shutdown_approved` / `shutdown_rejected` | Response to shutdown request |\n| `idle` | Notification sent when an agent has no more work |\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Task Status Events\n\nTask state transitions trigger automatic event behavior. When a task status changes, the system automatically propagates effects to dependent tasks.\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Task not yet started |\n| `in_progress` | Task currently being worked on |\n| `completed` | Task done — auto-unblocks dependent tasks |\n| `blocked` | Task waiting on other tasks to complete |\n\nWhen a task is marked `completed`, any tasks blocked by it are automatically unblocked (moved from `blocked` to `pending` if no other blockers remain).\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Inter-Agent Communication Flow\n\n```mermaid\ngraph TD\n A[Agent] -->|message| B[Team Inbox]\n A -->|broadcast| C[All Members]\n A -->|join_request| D[Leader]\n D -->|join_approved| A\n A -->|plan_approval_request| D\n D -->|plan_approved
plan_rejected| A\n A -->|shutdown_request| E[Target Agent]\n E -->|shutdown_approved
shutdown_rejected| A\n A -->|idle| D\n```\n\n## Board and Inbox Architecture\n\nThe board system serves as the persistent event store, maintaining message history and team state.\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # TeamConfig (name, members, leader)\n│ └── inboxes/{agent}/ # msg-{timestamp}-{uuid}.json files\n├── tasks/{team}/\n│ └── task-{id}.json # Individual task files\n└── plans/\n └── {agent}-{id}.md # Plan documents\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n### Board Show Command\n\nThe `board show` command displays team board data with member-aware message aliases:\n\n```bash\nclawteam board show \nclawteam --json board show \n```\n\nRecent board payloads include:\n- `memberKey` — identifies team member\n- `inboxName` — target inbox identifier\n- `fromLabel` / `toLabel` — message source and destination\n\nThese fields are used by the browser board to filter inbox history.\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Lifecycle Event Commands\n\nThe CLI provides commands for managing agent lifecycle events:\n\n### Idle Notification\n\nSend when an agent has no more work:\n\n```bash\nclawteam lifecycle idle [--last-task ID] [--task-status STATUS]\n```\n\n### Shutdown Sequence\n\n```bash\n# Request shutdown\nclawteam lifecycle request-shutdown [--reason TEXT]\n\n# Accept shutdown\nclawteam lifecycle approve-shutdown \n\n# Reject shutdown\nclawteam lifecycle reject-shutdown [--reason TEXT]\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Plan Submission Events\n\nAgents submit plans for leader approval, creating an approval workflow:\n\n```mermaid\nsequenceDiagram\n Agent->>Leader: plan submit \n Note over Leader: Reviews plan\n Leader->>Agent: plan approve \n Note over Agent: Plan approved, proceed with work\n```\n\n### Plan Commands\n\n```bash\n# Submit a plan\nclawteam plan submit [--summary TEXT]\n\n# Approve a plan\nclawteam plan approve [--feedback TEXT]\n\n# Reject a plan\nclawteam plan reject [--feedback TEXT]\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md]()\n\n## Context Recovery Hooks\n\nThe harness system integrates with the event system through context recovery hooks that provide role-aware information to agents:\n\n```python\ndef _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:\n \"\"\"Layer 5: One-liner teammate summaries.\"\"\"\n from clawteam.team.models import TaskStatus\n from clawteam.team.tasks import TaskStore\n store = TaskStore(team_name)\n tasks = store.list_tasks()\n```\n\n资料来源：[clawteam/harness/context_recovery.py:53-59]()\n\nDifferent roles receive different context:\n\n| Role | Context Provided |\n|------|------------------|\n| `executor` | Sprint contract artifact containing their assignment |\n| `evaluator` | Full spec.md content and all contract criteria |\n| `planner` | Spec draft content for planning purposes |\n\n资料来源：[clawteam/harness/context_recovery.py:31-47]()\n\n## Spawn Backend Event Integration\n\nThe wsh backend demonstrates how spawned agents integrate with the event system for runtime message injection:\n\n```python\ndef inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n \"\"\"Best-effort runtime injection into a running wsh block.\"\"\"\n from clawteam.spawn.registry import get_registry\n\n info = get_registry(team).get(agent_name, {})\n block_id = info.get(\"block_id\", \"\") or self._blocks.get(agent_name, \"\")\n if not block_id:\n return False, f\"wsh block for '{team}/{agent_name}' not found\"\n```\n\nThe 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.\n\n资料来源：[clawteam/spawn/wsh_backend.py:52-61]()\n\n## See Also\n\n- [CLI Reference](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) — Complete command documentation\n- [Task System](../team/tasks) — Task management and dependencies\n- [Spawn System](../spawn/index) — Agent spawning and backend management\n\n---\n\n\n\n## Agent Spawning System\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quickstart), [Team Management](#page-team-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [clawteam/spawn/__init__.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/__init__.py)\n- [clawteam/spawn/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/base.py)\n- [clawteam/spawn/adapters.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/adapters.py)\n- [clawteam/spawn/tmux_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/tmux_backend.py)\n- [clawteam/spawn/subprocess_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/subprocess_backend.py)\n- [clawteam/spawn/profiles.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/profiles.py)\n- [clawteam/spawn/presets.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/presets.py)\n- [clawteam/spawn/prompt.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/prompt.py)\n- [clawteam/spawn/sessions.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/sessions.py)\n- [clawteam/spawn/session_locators/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_locators/base.py)\n
\n\n# Agent Spawning System\n\nThe 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.\n\n## Architecture Overview\n\nThe 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.\n\n```mermaid\ngraph TD\n A[CLI Command: clawteam spawn] --> B[SpawnCommand Handler]\n B --> C[Backend Factory]\n C --> D[subprocess Backend]\n C --> E[tmux Backend]\n C --> F[wsh Backend]\n D --> G[Agent Process]\n E --> H[tmux Session]\n F --> I[wsh Block]\n G --> J[Session Store]\n H --> J\n I --> J\n J --> K[Registry]\n K --> L[Team Coordination]\n```\n\n## Core Components\n\n### Spawn Backends\n\nThe system supports three execution backends, each providing different isolation and management capabilities:\n\n| Backend | Description | Use Case |\n|---------|-------------|----------|\n| `subprocess` | Direct child process management | Simple single-agent scenarios |\n| `tmux` | Terminal multiplexer sessions | Persistent sessions with attach capability |\n| `wsh` | weish block isolation | Isolated workspace blocks |\n\n#### Base Backend Interface\n\nAll backends implement a common interface defined in `base.py`:\n\n```python\nclass SpawnBackend(ABC):\n @abstractmethod\n def spawn(\n self,\n command: list[str],\n team_name: str,\n agent_name: str,\n agent_type: str,\n cwd: str | None = None,\n env: dict[str, str] | None = None,\n **kwargs\n ) -> str:\n \"\"\"Spawn an agent process and return result message.\"\"\"\n pass\n \n @abstractmethod\n def list_running(self) -> list[dict[str, str]]:\n \"\"\"List currently running agents.\"\"\"\n pass\n \n @abstractmethod\n def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n \"\"\"Inject a runtime notification into a running agent.\"\"\"\n pass\n```\n\n资料来源：[clawteam/spawn/base.py:1-50]()\n\n### Agent Registry\n\nWhen an agent is spawned, it is registered in a centralized registry that tracks all active agents per team:\n\n```python\nfrom clawteam.spawn.registry import register_agent\n\nregister_agent(\n team_name=team_name,\n agent_name=agent_name,\n backend=\"tmux\",\n block_id=session_name,\n pid=process.pid,\n command=list(final_command),\n)\n```\n\n资料来源：[clawteam/spawn/tmux_backend.py](), [clawteam/spawn/wsh_backend.py:1-50]()\n\nThe registry maintains the following information per agent:\n- `team_name`: The team the agent belongs to\n- `agent_name`: Unique identifier within the team\n- `backend`: Backend type (subprocess/tmux/wsh)\n- `block_id` / `session_name`: Backend-specific identifier\n- `pid`: Process ID (for subprocess backend)\n- `command`: Original spawn command\n\n## Spawn Command Interface\n\n### CLI Syntax\n\n```bash\nclawteam spawn [options]\n```\n\n### Command Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--team, -t` | Team name | `\"default\"` |\n| `--agent-name, -n` | Agent name | auto-generated |\n| `--agent-type` | Agent type | `\"general-purpose\"` |\n\n### Example Usage\n\n```bash\n# Spawn Claude Code agent in tmux\nclawteam spawn tmux claude --team dev-team --agent-name builder --agent-type researcher\n\n# Spawn in subprocess backend\nclawteam spawn subprocess claude-code --team analysis --agent-name analyzer\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md](), [clawteam/cli/commands.py]()\n\n## Agent Identity System\n\nWhen spawning an agent, the system automatically configures environment variables that establish the agent's identity within the team:\n\n```bash\nexport CLAWTEAM_AGENT_ID=\"\"\nexport CLAWTEAM_AGENT_NAME=\"\"\nexport CLAWTEAM_AGENT_TYPE=\"\"\nexport CLAWTEAM_TEAM_NAME=\"\"\n```\n\nAgents can verify their identity using:\n\n```bash\nclawteam identity show\n```\n\n资料来源：[clawteam/cli/commands.py](), [skills/clawteam/references/cli-reference.md]()\n\n## Session Management\n\n### Session Persistence\n\nThe system tracks agent sessions to enable resume functionality:\n\n```python\nfrom clawteam.spawn.sessions import SessionStore\n\nsession_store = SessionStore(team_name)\nsession = session_store.load(agent_name)\n\nif session and session.session_id:\n resumed_command = build_cli_resume_command(command, session.session_id, client=client)\n```\n\n资料来源：[clawteam/spawn/sessions.py](), [clawteam/spawn/session_capture.py]()\n\n### Session Lifecycle\n\n```mermaid\ngraph LR\n A[Spawn] --> B[Create Session]\n B --> C[Store in SessionStore]\n C --> D[Execute Agent]\n D --> E[Agent Completes]\n E --> F[Session Archived]\n F --> G[Resume Available]\n G --> H[Resume Command]\n H --> D\n```\n\n### Session Locators\n\nSession locators find existing sessions across different backends:\n\n```python\nfrom clawteam.spawn.session_locators.base import SessionLocator\n\nclass SessionLocator(ABC):\n @abstractmethod\n def find_session(self, team: str, agent: str) -> SessionInfo | None:\n \"\"\"Locate an existing session for the given team/agent.\"\"\"\n pass\n```\n\n资料来源：[clawteam/spawn/session_locators/base.py]()\n\n## Profile and Preset System\n\n### Profiles\n\nProfiles are reusable configurations that define how agents should be spawned:\n\n```bash\n# List available profiles\nclawteam profile list\n\n# Test a profile\nclawteam profile test claude-kimi\n\n# Generate profile from preset\nclawteam preset generate-profile moonshot-cn claude --name claude-kimi\n```\n\n资料来源：[clawteam/spawn/profiles.py](), [skills/clawteam/SKILL.md]()\n\n### Presets\n\nPresets are provider templates used to generate profiles:\n\n| Preset | Provider |\n|--------|----------|\n| `moonshot-cn` | Moonshot CN |\n| `claude` | Anthropic Claude |\n| `openai` | OpenAI |\n| Custom | User-defined |\n\n```bash\n# List presets\nclawteam preset list\n\n# Show preset details\nclawteam preset show moonshot-cn\n```\n\n资料来源：[clawteam/spawn/presets.py](), [skills/clawteam/references/workflows.md]()\n\n## Prompt Generation\n\nWhen spawning an agent, ClawTeam generates a comprehensive system prompt that includes identity information, task details, and coordination instructions:\n\n```python\nfrom clawteam.spawn.prompt import build_agent_prompt\n\nprompt = build_agent_prompt(\n agent_name=agent_name,\n agent_id=agent_id,\n agent_type=agent_type,\n team_name=team_name,\n leader_name=leader_name,\n task=task,\n user=user_name,\n workspace_dir=cwd,\n workspace_branch=ws_branch,\n isolated_workspace=bool(workspace and cwd),\n repo_path=repo,\n)\n```\n\n资料来源：[clawteam/spawn/prompt.py](), [clawteam/cli/commands.py]()\n\n### Prompt Components\n\nThe generated prompt includes:\n1. **Identity block**: Agent name, ID, type, and team\n2. **Task description**: Assigned work from the team leader\n3. **Coordination guide**: How to use ClawTeam CLI for task updates\n4. **Workspace context**: Directory, branch, git state\n\n## Skill Loading\n\nAgents can be spawned with predefined skills loaded from `~/.claude/skills/`:\n\n```python\ndef _load_skill_content(name: str) -> str | None:\n \"\"\"Load skill content from ~/.claude/skills.\"\"\"\n skills_root = Path.home() / \".claude\" / \"skills\"\n skill_dir = skills_root / name\n \n # Support both directory and single-file formats\n if skill_dir.is_dir():\n skill_file = skill_dir / \"SKILL.md\"\n # Fallback to first .md file\n else:\n single_file = skills_root / f\"{name}.md\"\n```\n\n资料来源：[clawteam/cli/commands.py]()\n\n### Supported Skill Formats\n\n- Directory format: `skills//SKILL.md`\n- Single file format: `skills/.md`\n\n## Runtime Message Injection\n\nThe system supports injecting runtime notifications into running agents:\n\n```python\ndef inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n \"\"\"Best-effort runtime injection into a running agent.\"\"\"\n from clawteam.spawn.registry import get_registry\n \n info = get_registry(team).get(agent_name, {})\n block_id = info.get(\"block_id\", \"\")\n \n if not block_id:\n return False, f\"Agent '{team}/{agent_name}' not found\"\n \n # Render and send notification\n payload = render_runtime_notification(envelope)\n```\n\n资料来源：[clawteam/spawn/wsh_backend.py](), [clawteam/spawn/base.py]()\n\n## Team Template Launch\n\nFor complex multi-agent scenarios, ClawTeam supports launching entire teams from templates:\n\n```bash\nclawteam launch