Skip to content
Back to search

ClawTeam

"ClawTeam: Agent Swarm Intelligence" (One Command → Full Automation)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hkuds--clawteam/badge.svg)](/listings/hkuds--clawteam)

HTML

<a href="/listings/hkuds--clawteam"><img src="/api/listings/hkuds--clawteam/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install clawteam

# Or install into an isolated user venv at ~/.clawteam/.venv
scripts/install_clawteam.sh

# Or from source
git clone https://github.com/HKUDS/ClawTeam.git
cd ClawTeam
pip install -e .

# Or install this checkout into ~/.clawteam/.venv
scripts/clawteam_local_install

# Optional: P2P transport (ZeroMQ)
pip install -e ".[p2p]"

Requires **Python 3.10+**, **tmux**, and a CLI coding agent (e.g. `claude`, `codex`). The install scripts create/reuse `~/.clawteam/.venv`, link `~/.local/bin/clawteam`, and install/update the bundled `clawteam` skill for detected clients.

Skill install targets are detected from existing config directories, including Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode, Nanobot, Cursor, OpenHarness (`~/.openharness/skills`), and Ohmo (`~/.ohmo/skills`).

All `spawn` examples assume the agent CLI you name is already installed and available on `PATH`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 856 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center"><img src="assets/icon.png" alt="" width="64" style="vertical-align: middle;">&nbsp; ClawTeam: Agent Swarm Intelligence</h1>
  2. <p align="center">
  3. <strong>The Evolution of AI Agents 🚀: Solo 🤖 → Swarm 🦞🤖🤖🤖<br>
  4. ClawTeam: Let AI Agents Form Swarms, Think & Work Together, and Ship Faster</strong>
  5. </p>
  6. <p align="center">
  7. <a href="#-quick-start"><img src="https://img.shields.io/badge/Quick_Start-3_min-blue?style=for-the-badge" alt="Quick Start"></a>
  8. <a href="#-use-cases"><img src="https://img.shields.io/badge/Use_Cases-3_Demos-green?style=for-the-badge" alt="Use Cases"></a>
  9. <a href="#-features"><img src="https://img.shields.io/badge/Features-12+-purple?style=for-the-badge" alt="Features"></a>
  10. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"></a>
  11. </p>
  12. <p align="center">
  13. <img src="https://img.shields.io/badge/python-≥3.10-blue?logo=python&logoColor=white" alt="Python">
  14. <img src="https://img.shields.io/badge/typer-CLI-green" alt="Typer">
  15. <img src="https://img.shields.io/badge/agents-Claude_Code_%7C_Codex_%7C_Any_CLI-blueviolet" alt="Agents">
  16. <img src="https://img.shields.io/badge/transport-File_%7C_ZeroMQ_P2P-orange" alt="Transport">
  17. <a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
  18. <a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
  19. </p>
  20. **One Command Line: Full Automation.** — agents spawn swarms, delegate tasks, and deliver results.
  21. Human provides the goal. The Agent Team orchestrates everything else.
  22. Full compatibility with [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/codex), [OpenClaw](https://github.com/openclaw/openclaw), [nanobot](https://github.com/HKUDS/nanobot), [Cursor](https://cursor.com), and any CLI agent.&nbsp;&nbsp;[**中文文档**](README_CN.md) | [**한국어**](README_KR.md)
  23. ---
  24. ## 📰 News
  25. **2026-03-18** ClawTeam project launched publicly.
  26. **2026-03-23** ClawTeam `v0.2.0` is released today.
  27. **2026-03** The current baseline includes config management, multi-user workflows, Web UI, P2P transport, and team templates.
  28. ---
  29. ## ✨ ClawTeam's Key Features
  30. <table align="center" width="100%">
  31. <tr>
  32. <td width="25%" align="center" style="vertical-align: top; padding: 15px;">
  33. <h3>🔬 AI Research Automation</h3>
  34. <div align="center">
  35. <img src="https://img.shields.io/badge/AutoResearch-FF6B6B?style=for-the-badge&logo=pytorch&logoColor=white" alt="AutoResearch" />
  36. </div>
  37. <img src="assets/scene-autoresearch.png" width="180">
  38. <p align="center"><strong>• Large-Scale Automated ML Experimentation</strong></p>
  39. <p align="center"><strong>• AI Model Training & Optimization</strong></p>
  40. <p align="center"><strong>• AI-Driven Hypothesis Generation & Validation</strong></p>
  41. <p align="center"><strong>• Self-Improving Model Architectures</strong></p>
  42. </td>
  43. <td width="25%" align="center" style="vertical-align: top; padding: 15px;">
  44. <h3>🏗️ Agentic Engineering</h3>
  45. <div align="center">
  46. <img src="https://img.shields.io/badge/Full--Stack_Dev-4ECDC4?style=for-the-badge&logo=git&logoColor=white" alt="Engineering" />
  47. </div>
  48. <img src="assets/scene-engineering.png" width="180">
  49. <p align="center"><strong>• Autonomous Full-Stack Development</strong></p>
  50. <p align="center"><strong>• Self-Evolving Software</strong></p>
  51. <p align="center"><strong>• Collaborative Open Source Development</strong></p>
  52. <p align="center"><strong>• Real-Time System Integration</strong></p>
  53. </td>
  54. <td width="25%" align="center" style="vertical-align: top; padding: 15px;">
  55. <h3>💰 AI Hedge Fund</h3>
  56. <div align="center">
  57. <img src="https://img.shields.io/badge/Investment_Analysis-FFD93D?style=for-the-badge&logo=bitcoin&logoColor=black" alt="Hedge Fund" />
  58. </div>
  59. <img src="assets/scene-hedgefund.png" width="180">
  60. <p align="center"><strong>• Automated Market Research & Data Mining</strong></p>
  61. <p align="center"><strong>• Multi-Strategy Portfolio Optimization</strong></p>
  62. <p align="center"><strong>• Real-Time Risk Assessment</strong></p>
  63. <p align="center"><strong>• Algorithmic Trading Execution & Monitoring</strong></p>
  64. </td>
  65. <td width="25%" align="center" style="vertical-align: top; padding: 15px;">
  66. <h3>🎪 Your Own Swarm</h3>
  67. <div align="center">
  68. <img src="https://img.shields.io/badge/TOML_Templates-C77DFF?style=for-the-badge&logo=toml&logoColor=white" alt="Templates" />
  69. </div>
  70. <img src="assets/scene-template.png" width="180">
  71. <p align="center"><strong>• Custom Scientific Research Teams</strong></p>
  72. <p align="center"><strong>• Personalized Investment Committees</strong></p>
  73. <p align="center"><strong>• Business Operations Teams</strong></p>
  74. <p align="center"><strong>• Content Production Studios</strong></p>
  75. </td>
  76. </tr>
  77. </table>
  78. ---
  79. <table align="center" width="100%">
  80. <tr>
  81. <td width="50%" align="center" style="vertical-align: top; padding: 10px;">
  82. <strong>v0.1.0</strong>
  83. https://github.com/user-attachments/assets/7e2f0ecd-8fe3-4970-90ac-5c9669ff060c
  84. </td>
  85. <td width="50%" align="center" style="vertical-align: top; padding: 10px;">
  86. <strong>v0.2.0</strong>
  87. https://github.com/user-attachments/assets/fd23be91-5cf4-457c-a77e-bac24b76e58f
  88. </td>
  89. </tr>
  90. </table>
  91. ☝️ Intelligent leader agent orchestrates 8 specialized sub-agents across 8 H100 GPUs, autonomously designing experiments and dynamically reallocating resources based on real-time performance.
  92. 🧠 The system synthesizes breakthroughs across teams and evolves strategies independently — achieving full research automation without human intervention.
  93. <p align="center">
  94. <img src="assets/teaser.png" alt="ClawTeam - AI agents orchestrating themselves" width="800">
  95. </p>
  96. ---
  97. ## 🤔 Why ClawTeam?
  98. Current AI agents are powerful — but they work in **isolation**. When facing complex tasks, you're stuck manually coordinating multiple agents, juggling context, and stitching together fragmented results.
  99. **What if agents could think and work as a team?**
  100. ClawTeam unlocks **Agent Swarm Intelligence** — where AI agents self-organize into collaborative teams, intelligently divide complex work, share insights in real-time, and converge on breakthrough solutions.
  101. • **🚀 Spawns specialized sub-agents** — each with dedicated environments and focus areas
  102. • **📋 Designs intelligent task allocation** — with smart dependency management
  103. • **💬 Facilitates real-time coordination** — seamless inter-agent communication
  104. • **📊 Monitors team performance** — tracks progress and identifies bottlenecks
  105. • **🔄 Adapts strategies dynamically** — reallocates resources and redirects efforts
  106. #### ✨ The Result?
  107. You set the vision. The swarm executes with collective intelligence.
  108. <p align="center">
  109. <img src="assets/comic-how-it-works.png" alt="How ClawTeam works - comic" width="700">
  110. </p>
  111. ---
  112. ## 🎯 Swarm Intelligence in Action
  113. <table>
  114. <tr>
  115. <td width="33%">
  116. ### 🦞 Agents Spawn Agents
  117. The leader agent calls `clawteam spawn` to create workers. Each worker gets its own **git worktree**, **tmux window**, and **identity** — automatically.
  118. ```bash
  119. # The leader agent runs:
  120. clawteam spawn --team my-team \
  121. --agent-name worker1 \
  122. --task "Implement auth module"
  123. ```
  124. </td>
  125. <td width="33%">
  126. ### 🤖 Agents Talk to Agents
  127. Workers check their inbox, update task status, and report results — all through CLI commands that are **auto-injected** into their prompt.
  128. ```bash
  129. # A worker agent checks tasks:
  130. clawteam task list my-team --owner me
  131. # Then reports back:
  132. clawteam inbox send my-team leader \
  133. "Auth done. All tests passing."
  134. ```
  135. </td>
  136. <td width="33%">
  137. ### 👀 You Just Watch
  138. Monitor the swarm from a tiled tmux view or a Web UI. The leader handles coordination — you intervene only when you want to.
  139. ```bash
  140. # Watch all agents simultaneously
  141. clawteam board attach my-team
  142. # Or open the web dashboard
  143. clawteam board serve --port 8080
  144. ```
  145. </td>
  146. </tr>
  147. </table>
  148. | | ClawTeam | Other multi-agent frameworks |
  149. |---|---------|----------------------------|
  150. | 🎯 **Who uses it** | **The AI agents themselves** | Humans writing orchestration code |
  151. | ⚡ **Setup** | `pip install` + one prompt to the leader | Docker, cloud APIs, YAML configs |
  152. | 🏗️ **Infrastructure** | Just a filesystem and tmux | Redis, message queues, databases |
  153. | 🤖 **Agent support** | Any CLI agent (Claude Code, Codex, OpenClaw, custom) | Framework-specific only |
  154. | 🌳 **Isolation** | Git worktrees (real branches, real diffs) | Containers or virtual envs |
  155. | 🧠 **Intelligence** | Swarm self-organizes via CLI commands | Hard-coded orchestration logic |
  156. ---
  157. ## 🎬 Use Cases
  158. ### 🔬 1. Autonomous ML Research — 8 Agents × 8 H100 GPUs
  159. Based on [@karpathy's autoresearch](https://github.com/karpathy/autoresearch).
  160. #### 💫 One Command. Full Automation.
  161. #### Human input: "Optimize this LLM training setup using 8 GPUs"
  162. The Agent Team handles everything else:
  163. - Spawns 8 specialized research agents across H100s
  164. - Designs 2000+ autonomous experiments
  165. - Achieves breakthrough improvements (val_bpb: 1.044→0.977)
  166. - Zero human intervention required
  167. #### 🎯 Pure Research at Scale
  168. Transform months of manual hyperparameter tuning into hours of intelligent automation.
  169. <p align="center">
  170. <img src="assets/autoresearch-progress.png" alt="AutoResearch Progress" width="720">
  171. <br>
  172. <em>🏆 val_bpb: 1.044 → 0.977 (6.4% improvement) | 2430+ experiments | ~30 GPU-hours</em>
  173. </p>
  174. **What agent team did autonomously:**
  175. ```
  176. Human prompt: "Use 8 GPUs to optimize train.py. Read program.md for instructions."
  177. 🦞 Leader agent's actions:
  178. ├── 📖 Read program.md, understand the experiment protocol
  179. ├── 🏗️ clawteam team spawn-team autoresearch
  180. ├── 🚀 Assigned each GPU a research direction:
  181. │ ├── GPU 0: clawteam spawn --task "Explore model depth (DEPTH 10-16)"
  182. │ ├── GPU 1: clawteam spawn --task "Explore model width (ASPECT_RATIO 80-128)"
  183. │ ├── GPU 2: clawteam spawn --task "Tune learning rates and optimizer"
  184. │ ├── GPU 3: clawteam spawn --task "Explore batch size and accumulation"
  185. │ ├── GPU 4-7: clawteam spawn tmux codex --task "..." (Codex agents)
  186. │ └── 🌳 Each agent: own git worktree, own branch, isolated experiments
  187. ├── 🔄 Every 30 minutes, checked results:
  188. │ ├── clawteam board show autoresearch
  189. │ ├── Read each agent's results.tsv
  190. │ ├── 🏆 Identified best findings (depth=12, batch=2^17, norm-before-RoPE)
  191. │ └── 📡 Cross-pollinated: told new agents to start from the best config
  192. ├── 🔧 When agents finished, reassigned GPUs:
  193. │ ├── Killed idle agents, cleaned worktrees
  194. │ ├── Created new worktrees from the best commit
  195. │ └── Spawned fresh agents with combined optimization directions
  196. └── ✅ After 2430+ experiments: val_bpb 1.044 → 0.977
  197. ```
  198. Full results: [novix-science/autoresearch](https://github.com/novix-science/autoresearch)
  199. ---
  200. ### 🏗️ 2. Agentic Software Engineering
  201. You tell Claude Code: *"Build me a full-stack todo app."* Claude realizes this is a multi-module task and **self-organizes a team**:
  202. ```
  203. Human prompt: "Build a full-stack todo app with auth, database, and React frontend."
  204. 🦞 Leader agent's actions:
  205. ├── 🏗️ clawteam team spawn-team webapp -d "Full-stack todo app"
  206. ├── 📋 Created tasks with dependency chains:
  207. │ ├── T1: "Design REST API schema" → architect
  208. │ ├── T2: "Implement JWT auth" --blocked-by T1 → backend1
  209. │ ├── T3: "Build database layer" --blocked-by T1 → backend2
  210. │ ├── T4: "Build React frontend" → frontend
  211. │ └── T5: "Integration tests" --blocked-by T2,T3,T4 → tester
  212. ├── 🚀 Spawned 5 sub-agents (each in its own git worktree):
  213. │ ├── clawteam spawn --agent-name architect --task "Design the API schema"
  214. │ ├── clawteam spawn --agent-name backend1 --task "Implement JWT auth"
  215. │ ├── clawteam spawn --agent-name backend2 --task "Build PostgreSQL models"
  216. │ ├── clawteam spawn --agent-name frontend --task "Build React UI"
  217. │ └── clawteam spawn --agent-name tester --task "Write pytest tests"
  218. ├── 🔗 Dependency auto-resolution:
  219. │ ├── architect completes → backend1 and backend2 auto-unblock
  220. │ ├── All backends complete → tester auto-unblocks
  221. │ └── Each agent calls: clawteam task update <id> --status completed
  222. ├── 💬 Sub-agents coordinate via inbox:
  223. │ ├── architect → backend1: "Here's the OpenAPI spec: ..."
  224. │ ├── backend1 → tester: "Auth endpoints ready at /api/auth/*"
  225. │ └── tester → leader: "All 47 tests passing ✅"
  226. └── 🌳 Leader merges all worktrees into main branch
  227. ```
  228. ---
  229. ### 💰 3. AI Hedge Fund — One-Command Team Launch
  230. A pre-built TOML template spawns a complete **7-agent** investment analysis team:
  231. ```bash
  232. # One command launches everything:
  233. clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"
  234. ```
  235. ```
  236. 🦞 What happens automatically:
  237. ├── 📊 Portfolio Manager (leader) spawns and receives the goal
  238. ├── 🤖 5 Analyst agents spawn, each with a different strategy:
  239. │ ├── 🎩 Buffett Analyst → value investing (moat, ROE, DCF)
  240. │ ├── 🚀 Growth Analyst → disruption (TAM, network effects)
  241. │ ├── 📈 Technical Analyst → indicators (EMA, RSI, Bollinger)
  242. │ ├── 📋 Fundamentals → financial ratios (P/E, D/E, FCF)
  243. │ └── 📰 Sentiment Analyst → news + insider trading signals
  244. ├── 🛡️ Risk Manager spawns, waits for all analyst signals:
  245. │ ├── clawteam inbox receive fund1 (collects all 5 signals)
  246. │ ├── Consolidates + computes position limits
  247. │ └── clawteam inbox send fund1 portfolio-manager "RISK REPORT: ..."
  248. └── 💼 Portfolio Manager makes final buy/sell/hold decisions
  249. ```
  250. Templates are TOML files — **create your own team archetypes** for any domain.
  251. ---
  252. ## 📦 Install
  253. ```bash
  254. pip install clawteam
  255. # Or install into an isolated user venv at ~/.clawteam/.venv
  256. scripts/install_clawteam.sh
  257. # Or from source
  258. git clone https://github.com/HKUDS/ClawTeam.git
  259. cd ClawTeam
  260. pip install -e .
  261. # Or install this checkout into ~/.clawteam/.venv
  262. scripts/clawteam_local_install
  263. # Optional: P2P transport (ZeroMQ)
  264. pip install -e ".[p2p]"
  265. ```
  266. Requires **Python 3.10+**, **tmux**, and a CLI coding agent (e.g. `claude`, `codex`). The install scripts create/reuse `~/.clawteam/.venv`, link `~/.local/bin/clawteam`, and install/update the bundled `clawteam` skill for detected clients.
  267. Skill install targets are detected from existing config directories, including Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode, Nanobot, Cursor, OpenHarness (`~/.openharness/skills`), and Ohmo (`~/.ohmo/skills`).
  268. All `spawn` examples assume the agent CLI you name is already installed and available on `PATH`.
  269. ---
  270. ## 🚀 Quick Start
  271. If you're new to ClawTeam, follow this order:
  272. 1. Make sure `tmux` and your agent CLI run standalone on this machine.
  273. 2. Pick one path below: let an agent drive, or drive it manually.
  274. 3. Use the supported-agent table to choose the right `spawn` command.
  275. 4. If you're integrating a new agent, check the adapter notes before debugging.
  276. ### ✅ Before You Start
  277. Run these checks first:
  278. ```bash
  279. tmux -V
  280. clawteam --help
  281. # Replace claude with the agent you actually want to use:
  282. claude --version
  283. codex --version
  284. nanobot --help
  285. ```
  286. If the agent CLI does not run correctly by itself, `clawteam spawn` will not fix it.
  287. ### ⚡ Option 1: Let the Agent Drive (Recommended)
  288. ClawTeam ships with a reusable skill in `skills/clawteam/`.
  289. **Claude Code**
  290. Install the skill into `~/.claude/skills/clawteam`, then prompt:
  291. ```
  292. "Build a web app. Use clawteam to split the work across multiple agents."
  293. ```
  294. **Codex**
  295. Install the same skill into `$CODEX_HOME/skills/clawteam` (typically `~/.codex/skills/clawteam`), then prompt:
  296. ```
  297. Use $clawteam to split this task across multiple agents and coordinate the team to completion.
  298. ```
  299. The agent will automatically create a team, spawn workers, assign tasks, and coordinate — using `clawteam` CLI commands under the hood.
  300. ### 🔧 Option 2: Drive It Manually
  301. ```bash
  302. # 1. Create a team (you become the leader)
  303. clawteam team spawn-team my-team -d "Build the auth module" -n leader
  304. # 2. Spawn worker agents — each gets a git worktree, tmux window, and identity
  305. clawteam spawn --team my-team --agent-name alice --task "Implement the OAuth2 flow"
  306. clawteam spawn --team my-team --agent-name bob --task "Write unit tests for auth"
  307. # 3. Workers auto-receive a coordination prompt that teaches them to:
  308. # ✅ Check tasks: clawteam task list my-team --owner alice
  309. # ✅ Update status: clawteam task update my-team <id> --status completed
  310. # ✅ Message leader: clawteam inbox send my-team leader "Done!"
  311. # ✅ Report idle: clawteam lifecycle idle my-team
  312. # 4. Watch them work side-by-side
  313. clawteam board attach my-team
  314. ```
  315. ### 🧩 Profiles and Presets
  316. When you want to use a non-default provider, model, or API gateway, configure a
  317. **profile** first instead of manually exporting provider env vars each time.
  318. ```bash
  319. # See built-in provider templates
  320. clawteam preset list
  321. clawteam preset show moonshot-cn
  322. # Generate a reusable runtime profile from a preset
  323. clawteam preset generate-profile moonshot-cn claude --name claude-kimi
  324. # MiniMax (M2.7) — global or China endpoint
  325. clawteam preset generate-profile minimax-global claude --name claude-minimax
  326. clawteam preset generate-profile minimax-cn claude --name claude-minimax-cn
  327. # Or use the interactive TUI
  328. clawteam profile wizard
  329. # Claude Code on a fresh machine/home may need this once
  330. clawteam profile doctor claude
  331. # Smoke-test the profile before spawning workers
  332. MOONSHOT_API_KEY=... clawteam profile test claude-kimi
  333. MINIMAX_API_KEY=... clawteam profile test claude-minimax
  334. ```
  335. Rules of thumb:
  336. - `profile` is the final runtime object used by `spawn` / `launch`
  337. - `preset` is a reusable provider template that generates one or more profiles
  338. - `wizard` is the easiest path for first-time setup
  339. - `doctor` is mainly for Claude Code first-run onboarding state
  340. ### 🧭 Which Spawn Command Should I Use?
  341. Use `clawteam spawn [backend] [command] ...` with the command that already works on
  342. your machine:
  343. ```bash
  344. # Claude Code
  345. clawteam spawn tmux claude --team my-team --agent-name alice --task "Implement OAuth2"
  346. # Codex
  347. clawteam spawn tmux codex --team my-team --agent-name bob --task "Write frontend tests"
  348. # nanobot
  349. clawteam spawn tmux nanobot --team my-team --agent-name carol --task "Build the API"
  350. # A configured profile (recommended for non-default providers/models)
  351. clawteam spawn tmux --profile claude-kimi --team my-team --agent-name dave --task "Refactor the auth flow"
  352. ```
  353. Notes:
  354. - `tmux` is the default backend and is the best choice when you want to watch interactive agent UIs.
  355. - `subprocess` is better for one-shot tools or non-interactive scripts.
  356. - `nanobot` is normalized internally to `nanobot agent`, so the command above is the correct ClawTeam entrypoint.
  357. - Claude Code and Codex trust prompts in fresh worktrees are auto-confirmed by the tmux backend.
  358. - For non-default providers/models, prefer `--profile <name>` over manually exporting env vars inline.
  359. ### 🔌 Adding a Different Agent
  360. ClawTeam can work with agents beyond Claude Code, Codex, and nanobot, but the CLI
  361. must satisfy a small compatibility contract:
  362. 1. The command must exist on `PATH` and launch successfully outside ClawTeam.
  363. 2. The agent must be able to run inside a specific working directory or git worktree.
  364. 3. The agent must accept an initial task, either by command-line argument or interactive input.
  365. 4. The process must stay alive in `tmux` if it is meant to be interactive.
  366. If you're unsure, test the agent standalone first, then wrap it with:
  367. ```bash
  368. clawteam spawn subprocess <your-agent> --team my-team --agent-name test --task "Say OK"
  369. ```
  370. If that works, switch to `tmux` for interactive monitoring.
  371. ### 🤖 Supported Agents
  372. ClawTeam works with **any CLI agent** that can execute shell commands:
  373. All examples below assume the corresponding CLI already runs standalone on your machine.
  374. | Agent | Spawn Command | Status |
  375. |-------|--------------|--------|
  376. | [Claude Code](https://claude.ai/claude-code) | `clawteam spawn tmux claude --team ...` | ✅ Full support |
  377. | [Codex](https://openai.com/codex) | `clawteam spawn tmux codex --team ...` | ✅ Full support |
  378. | [OpenClaw](https://github.com/openclaw/openclaw) | `clawteam spawn tmux openclaw --team ...` | ✅ Full support |
  379. | [nanobot](https://github.com/HKUDS/nanobot) | `clawteam spawn tmux nanobot --team ...` | ✅ Full support |
  380. | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | `clawteam spawn tmux kimi --team ...` | ✅ Full support |
  381. | [Cursor](https://cursor.com) | `clawteam spawn subprocess cursor --team ...` | 🔮 Experimental |
  382. | Custom scripts | `clawteam spawn subprocess python --team ...` | ✅ Full support |
  383. For provider-aware setups such as Claude Code via Moonshot Kimi, MiniMax, or Gemini via
  384. Vertex, use `profile` + `preset` and then spawn with `--profile`.
  385. ---
  386. ## ✨ Features
  387. <table>
  388. <tr>
  389. <td width="50%">
  390. ### 🦞 Agent Self-Organization
  391. - Leader agents spawn and manage worker agents
  392. - **Auto-injected coordination prompt** — zero manual setup
  393. - Workers self-report status, results, and idle state
  394. - Works with any CLI agent: Claude Code, Codex, OpenClaw, custom
  395. ### 🌳 Workspace Isolation
  396. - Each agent gets its own **git worktree** (separate branch)
  397. - No merge conflicts between parallel agents
  398. - Checkpoint, merge, and cleanup commands
  399. - Branch naming: `clawteam/{team}/{agent}`
  400. ### 📋 Task Tracking with Dependencies
  401. - Shared kanban: `pending` → `in_progress` → `completed` / `blocked`
  402. - `--blocked-by` dependency chains — **auto-unblock on completion**
  403. - `task wait` blocks until all tasks complete
  404. - Filter by status, owner; JSON output for scripting
  405. </td>
  406. <td width="50%">
  407. ### 💬 Inter-Agent Messaging
  408. - Point-to-point **inboxes** (send, receive, peek)
  409. - **Broadcast** to all team members
  410. - File-based (default) or ZeroMQ P2P transport with offline fallback
  411. - Agents discover messages via `inbox receive`
  412. ### 📊 Monitoring & Dashboards
  413. - `board show` — terminal kanban board
  414. - `board live` — auto-refreshing dashboard
  415. - `board attach` — **tiled tmux view** of all agents working
  416. - `board serve` — **Web UI** with real-time updates
  417. ### 🎪 Team Templates
  418. - **TOML files** define team archetypes (roles, tasks, prompts)
  419. - One command launches a complete team: `clawteam launch <template>`
  420. - Built-in: AI Hedge Fund (7 agents). Create your own.
  421. - Variable substitution: `{goal}`, `{team_name}`, `{agent_name}`
  422. </td>
  423. </tr>
  424. </table>
  425. ### 🔧 More
  426. | Feature | Description |
  427. |---------|-------------|
  428. | 📝 **Plan Approval** | Agents submit plans for leader review before execution |
  429. | 🔄 **Lifecycle Protocol** | Graceful shutdown request/approve/reject, idle notifications |
  430. | 📊 **JSON Output** | `--json` flag on all commands — agents parse structured output |
  431. | 🌐 **Cross-Machine** | Shared filesystem (NFS/SSHFS) or P2P transport for distributed teams |
  432. | 👥 **Multi-User** | Namespace agents by user — multiple humans can share a team |
  433. | ⚙️ **Configuration** | Persistent config: env var > config file > default priority |
  434. | 🔌 **Agent Skill** | Reusable skill entry for Claude Code and Codex workflows |
  435. ---
  436. ## 🤖 How Agents Use ClawTeam
  437. When an agent is spawned via `clawteam spawn`, it receives an **auto-injected coordination prompt**:
  438. ```
  439. ## Coordination Protocol (auto-injected into every spawned agent)
  440. - 📋 Check your tasks: clawteam task list <team> --owner <your-name>
  441. - ▶️ Start a task: clawteam task update <team> <id> --status in_progress
  442. - ✅ Finish a task: clawteam task update <team> <id> --status completed
  443. - 💬 Message leader: clawteam inbox send <team> leader "status update..."
  444. - 💬 Message teammate: clawteam inbox send <team> <name> "info..."
  445. - 📨 Check inbox: clawteam inbox receive <team>
  446. - 😴 Report idle: clawteam lifecycle idle <team>
  447. ```
  448. This means **any CLI agent** can participate in a ClawTeam team — it just needs to run shell commands. No custom SDK, no API integration, no framework lock-in.
  449. ---
  450. ## 📖 Command Reference
  451. <details open>
  452. <summary><h3>🔧 Core Commands</h3></summary>
  453. ```bash
  454. # 🏗️ Team lifecycle
  455. clawteam team spawn-team <team> -d "description" -n <leader>
  456. clawteam team discover # List all teams
  457. clawteam team status <team> # Show members
  458. clawteam team cleanup <team> --force # Delete team
  459. # 🚀 Spawn agents
  460. clawteam spawn --team <team> --agent-name <name> --task "do this"
  461. clawteam spawn tmux codex --team <team> --agent-name <name> --task "do this"
  462. # 📋 Task management
  463. clawteam task create <team> "subject" -o <owner> --blocked-by <id1>,<id2>
  464. clawteam task update <team> <id> --status completed # auto-unblocks dependents
  465. clawteam task list <team> --status blocked --owner worker1
  466. clawteam task wait <team> --timeout 300
  467. # 💬 Messaging
  468. clawteam inbox send <team> <to> "message"
  469. clawteam inbox broadcast <team> "message"
  470. clawteam inbox receive <team> # consume messages
  471. clawteam inbox peek <team> # read without consuming
  472. # 📊 Monitoring
  473. clawteam board show <team> # terminal kanban
  474. clawteam board live <team> --interval 3 # auto-refresh
  475. clawteam board attach <team> # tiled tmux view
  476. clawteam board serve --port 8080 # web UI
  477. ```
  478. </details>
  479. <details>
  480. <summary><h3>🌳 Workspace, 📝 Plan, 🔄 Lifecycle, ⚙️ Config</h3></summary>
  481. ```bash
  482. # 🌳 Workspace (git worktree management)
  483. clawteam workspace list <team>
  484. clawteam workspace checkpoint <team> <agent> # auto-commit
  485. clawteam workspace merge <team> <agent> # merge back to main
  486. clawteam workspace cleanup <team> <agent> # remove worktree
  487. # 📝 Plan approval
  488. clawteam plan submit <team> <agent> "plan" --summary "TL;DR"
  489. clawteam plan approve <team> <plan-id> <agent> --feedback "LGTM"
  490. clawteam plan reject <team> <plan-id> <agent> --feedback "Revise X"
  491. # 🔄 Lifecycle
  492. clawteam lifecycle request-shutdown <team> <agent> --reason "done"
  493. clawteam lifecycle approve-shutdown <team> <request-id> <agent>
  494. clawteam lifecycle idle <team>
  495. # 🎪 Templates
  496. clawteam launch <template> --team <name> --goal "Build X"
  497. clawteam template list
  498. # ⚙️ Config
  499. clawteam config show
  500. clawteam config set transport p2p
  501. clawteam config health
  502. ```
  503. | Setting | Env Var | Default | Description |
  504. |---------|---------|---------|-------------|
  505. | `data_dir` | `CLAWTEAM_DATA_DIR` | `~/.clawteam` | Data directory |
  506. | `transport` | `CLAWTEAM_TRANSPORT` | `file` | `file` or `p2p` |
  507. | `workspace` | `CLAWTEAM_WORKSPACE` | `auto` | `auto` / `always` / `never` |
  508. | `default_backend` | `CLAWTEAM_DEFAULT_BACKEND` | `tmux` | `tmux` or `subprocess` |
  509. | `skip_permissions` | `CLAWTEAM_SKIP_PERMISSIONS` | `true` | Auto-approve agent tools |
  510. Legacy aliases:
  511. `OH_*` env vars are still accepted for compatibility, but new docs and examples use `CLAWTEAM_*`.
  512. </details>
  513. ---
  514. ## 🏗️ Architecture
  515. ```
  516. Human: "Optimize this LLM"
  517. │
  518. ▼
  519. ┌──────────────┐ clawteam spawn ┌──────────────┐
  520. │ 🦞 Leader │ ──────────────────────► │ 🤖 Worker │
  521. │ (Claude Code)│ ──────┐ │ (Claude Code)│
  522. │ │ │ │ git worktree │
  523. │ Uses: │ │ │ tmux window │
  524. │ • spawn │ │ clawteam spawn └──────────────┘
  525. │ • task create│ │
  526. │ • inbox send │ ▼ ┌──────────────┐
  527. │ • board show │ ──────────────────────► │ 🤖 Worker │
  528. │ • task wait │ │ │ (Codex) │
  529. └──────────────┘ │ │ git worktree │
  530. │ │ tmux window │
  531. │ clawteam spawn └──────────────┘
  532. ▼
  533. ┌──────────────┐
  534. │ 🤖 Worker │ Each worker uses:
  535. │ (any CLI) │ • task list (check work)
  536. │ git worktree │ • task update (report done)
  537. │ tmux window │ • inbox send (message leader)
  538. └──────────────┘ • inbox receive (get instructions)
  539. │
  540. ▼
  541. ┌─────────────────────┐
  542. │ ~/.clawteam/ │
  543. │ ├── teams/ (who) │
  544. │ ├── tasks/ (what)│
  545. │ ├── inboxes/ (talk)│
  546. │ └── workspaces/ │
  547. │ (isolated code)│
  548. └─────────────────────┘
  549. ```
  550. All state lives in `~/.clawteam/` as JSON files. No database, no server, no cloud. Atomic `tmp + rename` writes ensure crash safety.
  551. | Spawn Default | Value | Override |
  552. |---------------|-------|----------|
  553. | Backend | `tmux` | `clawteam spawn subprocess ...` |
  554. | Command | `claude` | `clawteam spawn tmux codex ...` |
  555. | Workspace | `auto` (git worktree) | `--no-workspace` |
  556. | Permissions | skip | `--no-skip-permissions` |
  557. | Transport | How it works | When to use |
  558. |-----------|-------------|-------------|
  559. | **file** (default) | JSON files in inbox dirs | Single machine, shared FS |
  560. | **p2p** | ZeroMQ PUSH/PULL + file fallback | Low-latency, auto-fallback |
  561. ---
  562. ## 🗺️ Roadmap
  563. | Phase | Version | What | Status |
  564. |-------|---------|------|--------|
  565. | **Current** | v0.3 | File + P2P (ZeroMQ) transport, Web UI, multi-user, team templates | ✅ Shipped |
  566. | **Phase 1** | v0.4 | Redis Transport — cross-machine messaging | 🔜 Planned |
  567. | **Phase 2** | v0.5 | Shared State Layer — team config and tasks across machines | 🔜 Planned |
  568. | **Phase 3** | v0.6 | Agent Marketplace — discover and reuse community agent templates | 💡 Exploring |
  569. | **Phase 4** | v0.7 | Adaptive Scheduling — dynamically reassign tasks based on agent performance | 💡 Exploring |
  570. | **Phase 5** | v1.0 | Production-grade — auth, permissions, audit logs | 💡 Exploring |
  571. ### Milestones
  572. | Milestone | Status | Notes |
  573. |---|---|---|
  574. | v0.1.x | ✅ Shipped | Core CLI, team/task/inbox flows, board, templates, packaging. |
  575. | v0.2.0 | ✅ Released | Stabilization, docs refresh, spawn/workspace fixes, and release packaging. |
  576. | v0.3 | 📍 Roadmap baseline | File + P2P transport, Web UI, multi-user workflow, team templates. |
  577. For the longer-term plan, see [ROADMAP.md](ROADMAP.md).
  578. ---
  579. ## 🤝 Contributing
  580. We welcome contributions! ClawTeam is designed to be extensible:
  581. - 🤖 **New agent integrations** — Add support for more AI coding agents
  582. - 🎪 **Team templates** — Create TOML templates for new domains (DevOps, data science, etc.)
  583. - 🔌 **Transport backends** — Redis, NATS, or other message transports
  584. - 📊 **Dashboard improvements** — Enhanced Web UI, Grafana integration
  585. - 📖 **Documentation** — Tutorials, best practices, agent prompt engineering guides
  586. ---
  587. ## 📖 Acknowledgements
  588. - [@karpathy/autoresearch](https://github.com/karpathy/autoresearch) — the autonomous ML research framework used in our 8-agent swarm demo
  589. - [Claude Code](https://claude.ai/claude-code) and [Codex](https://openai.com/codex) — AI coding agents that work as ClawTeam team members
  590. - [ai-hedge-fund](https://github.com/virattt/ai-hedge-fund) — inspiration for the multi-analyst hedge fund template
  591. - [CLI-Anything](https://github.com/HKUDS/CLI-Anything) — sister project making all software agent-native
  592. ---
  593. ## ⭐ Star History
  594. If you find ClawTeam helpful, please consider giving us a star! ⭐
  595. <div align="center">
  596. <a href="https://star-history.com/#HKUDS/ClawTeam&Date">
  597. <picture>
  598. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/ClawTeam&type=Date&theme=dark" />
  599. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/ClawTeam&type=Date" />
  600. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/ClawTeam&type=Date" />
  601. </picture>
  602. </a>
  603. </div>
  604. ## 📄 License
  605. MIT License — free to use, modify, and distribute.
  606. ---
  607. <div align="center">
  608. **ClawTeam** — *Agent Swarm Intelligence.* 🦞
  609. <sub>8 agents × 8 H100s × 2430 experiments × one CLI × one swarm</sub>
  610. <br>
  611. <img src="assets/icon.png" alt="ClawTeam" width="80">
  612. </div>
  613. <p align="center">
  614. <em>Thanks for visiting ✨ ClawTeam!</em><br><br>
  615. <img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.ClawTeam&style=for-the-badge&color=00d4ff" alt="Views">
  616. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.