Skip to content
Back to search

ClawTeam-OpenClaw

ClawTeam fork fully adapted for OpenClaw — multi-agent swarm coordination with OpenClaw as the default agent

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/win4r--clawteam-openclaw/badge.svg)](/listings/win4r--clawteam-openclaw)

HTML

<a href="/listings/win4r--clawteam-openclaw"><img src="/api/listings/win4r--clawteam-openclaw/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.

Option 1: Let the Agent Drive (Recommended)

Install ClawTeam, then prompt your agent:

"Build a web app. Use clawteam to split the work across multiple agents."

The agent auto-creates a team, spawns workers, assigns tasks, and coordinates — all via `clawteam` CLI.

Option 2: Drive It Manually

# Create a team
clawteam team spawn-team my-team -d "Build the auth module" -n leader

# Spawn workers — each gets a git worktree plus its own backend session
clawteam spawn --team my-team --agent-name alice --task "Implement OAuth2 flow"
clawteam spawn --team my-team --agent-name bob   --task "Write unit tests for auth"

# Watch them work
clawteam board serve --port 8080
clawteam board attach my-team   # Linux/macOS/WSL with tmux

Supported Agents

| Agent | Spawn Command | Status | |-------|--------------|--------| | [OpenClaw](https://openclaw.ai) | `clawteam spawn --team ...` | **Default** | | [Claude Code](https://claude.ai/claude-code) | `clawteam spawn claude --team ...` | Full support | | [Codex](https://openai.com/codex) | `clawteam spawn codex --team ...` | Full support | | [nanobot](https://github.com/HKUDS/nanobot) | `clawteam spawn nanobot --team ...` | Full support | | [Hermes Agent](https://github.com/NousResearch/hermes-agent) | `clawteam spawn hermes --team ...` | Full support (tmux + subprocess) | | [Cursor](https://cursor.com) | `clawteam spawn subprocess cursor --team ...` | Experimental | | Custom scripts | `clawteam spawn subprocess python --team ...` | Full support |

---

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 · 714 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # [🚀观看我的哔哩哔哩视频](https://space.bilibili.com/3493277319825652)
  2. <p align="center">
  3. <a href="README.md">English</a> |
  4. <a href="README_CN.md">简体中文</a> |
  5. <a href="README_TW.md">繁體中文</a> |
  6. <a href="README_JA.md">日本語</a> |
  7. <a href="README_KO.md">한국어</a> |
  8. <a href="README_FR.md">Français</a> |
  9. <a href="README_ES.md">Español</a> |
  10. <a href="README_DE.md">Deutsch</a> |
  11. <a href="README_IT.md">Italiano</a> |
  12. <a href="README_RU.md">Русский</a> |
  13. <a href="README_PT-BR.md">Português (Brasil)</a>
  14. </p>
  15. <h1 align="center">🦞ClawTeam-OpenClaw</h1>
  16. <p align="center">
  17. <strong>Multi-agent swarm coordination for CLI coding agents — <a href="https://openclaw.ai">OpenClaw</a> as default</strong>
  18. </p>
  19. <p align="center">
  20. <a href="https://github.com/HKUDS/ClawTeam"><img src="https://img.shields.io/badge/upstream-HKUDS%2FClawTeam-purple?style=for-the-badge" alt="Upstream"></a>
  21. <a href="#-quick-start"><img src="https://img.shields.io/badge/Quick_Start-3_min-blue?style=for-the-badge" alt="Quick Start"></a>
  22. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"></a>
  23. </p>
  24. <p align="center">
  25. <img src="https://img.shields.io/badge/python-≥3.10-blue?logo=python&logoColor=white" alt="Python">
  26. <img src="https://img.shields.io/badge/agents-OpenClaw_%7C_Claude_Code_%7C_Codex_%7C_Hermes_%7C_nanobot-blueviolet" alt="Agents">
  27. <img src="https://img.shields.io/badge/transport-File_%7C_ZeroMQ_P2P-orange" alt="Transport">
  28. <img src="https://img.shields.io/badge/version-0.3.0-teal" alt="Version">
  29. </p>
  30. > **Fork of [HKUDS/ClawTeam](https://github.com/HKUDS/ClawTeam)** with deep OpenClaw integration: default `openclaw` agent, per-agent session isolation, exec approval auto-config, and production-hardened spawn backends. All upstream fixes are synced.
  31. You set the goal. The agent swarm handles the rest — spawning workers, splitting tasks, coordinating, and merging results.
  32. Works with [OpenClaw](https://openclaw.ai) (default), [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/codex), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [nanobot](https://github.com/HKUDS/nanobot), [Cursor](https://cursor.com), and any CLI agent.
  33. ## Platform Support
  34. - Linux and macOS keep the original `tmux`-first workflow.
  35. - Windows 10/11 is supported with an automatic fallback to the `subprocess` backend.
  36. - Task locking, process liveness checks, and signal registration are routed through a shared compatibility layer so unsupported Unix-only behavior degrades safely on Windows.
  37. - `board attach` still requires `tmux`, so on Windows prefer `clawteam board serve` for live monitoring.
  38. - If you want the original tmux workflow on Windows, run ClawTeam inside WSL.
  39. ---
  40. ## Why ClawTeam?
  41. Current AI agents are powerful but work in **isolation**. ClawTeam lets agents self-organize into teams — splitting work, communicating, and converging on results without human micromanagement.
  42. | | ClawTeam | Other multi-agent frameworks |
  43. |---|---------|----------------------------|
  44. | **Who uses it** | The AI agents themselves | Humans writing orchestration code |
  45. | **Setup** | `pip install` + one prompt | Docker, cloud APIs, YAML configs |
  46. | **Infrastructure** | Filesystem + tmux | Redis, message queues, databases |
  47. | **Agent support** | Any CLI agent | Framework-specific only |
  48. | **Isolation** | Git worktrees (real branches) | Containers or virtual envs |
  49. ---
  50. ## How It Works
  51. <table>
  52. <tr>
  53. <td width="33%">
  54. ### Agents Spawn Agents
  55. The leader calls `clawteam spawn` to create workers. Each gets its own **git worktree**, **spawn backend session**, and **identity**.
  56. ```bash
  57. clawteam spawn --team my-team \
  58. --agent-name worker1 \
  59. --task "Implement auth module"
  60. ```
  61. </td>
  62. <td width="33%">
  63. ### Agents Talk to Agents
  64. Workers check inboxes, update tasks, and report results — all through CLI commands **auto-injected** into their prompt.
  65. ```bash
  66. clawteam task list my-team --owner me
  67. clawteam inbox send my-team leader \
  68. "Auth done. All tests passing."
  69. ```
  70. </td>
  71. <td width="33%">
  72. ### You Just Watch
  73. Monitor the swarm from a tiled tmux view or Web UI. The leader handles coordination.
  74. ```bash
  75. clawteam board serve --port 8080
  76. # Or, on Linux/macOS/WSL with tmux:
  77. clawteam board attach my-team
  78. ```
  79. </td>
  80. </tr>
  81. </table>
  82. ---
  83. ## Quick Start
  84. ### Option 1: Let the Agent Drive (Recommended)
  85. Install ClawTeam, then prompt your agent:
  86. ```
  87. "Build a web app. Use clawteam to split the work across multiple agents."
  88. ```
  89. The agent auto-creates a team, spawns workers, assigns tasks, and coordinates — all via `clawteam` CLI.
  90. ### Option 2: Drive It Manually
  91. ```bash
  92. # Create a team
  93. clawteam team spawn-team my-team -d "Build the auth module" -n leader
  94. # Spawn workers — each gets a git worktree plus its own backend session
  95. clawteam spawn --team my-team --agent-name alice --task "Implement OAuth2 flow"
  96. clawteam spawn --team my-team --agent-name bob --task "Write unit tests for auth"
  97. # Watch them work
  98. clawteam board serve --port 8080
  99. clawteam board attach my-team # Linux/macOS/WSL with tmux
  100. ```
  101. ### Supported Agents
  102. | Agent | Spawn Command | Status |
  103. |-------|--------------|--------|
  104. | [OpenClaw](https://openclaw.ai) | `clawteam spawn --team ...` | **Default** |
  105. | [Claude Code](https://claude.ai/claude-code) | `clawteam spawn claude --team ...` | Full support |
  106. | [Codex](https://openai.com/codex) | `clawteam spawn codex --team ...` | Full support |
  107. | [nanobot](https://github.com/HKUDS/nanobot) | `clawteam spawn nanobot --team ...` | Full support |
  108. | [Hermes Agent](https://github.com/NousResearch/hermes-agent) | `clawteam spawn hermes --team ...` | Full support (tmux + subprocess) |
  109. | [Cursor](https://cursor.com) | `clawteam spawn subprocess cursor --team ...` | Experimental |
  110. | Custom scripts | `clawteam spawn subprocess python --team ...` | Full support |
  111. ---
  112. ## Install
  113. ### Step 1: Prerequisites
  114. ClawTeam requires **Python 3.10+** and at least one CLI coding agent (OpenClaw, Claude Code, Codex, etc.). On Linux/macOS, the full visual workflow also requires **tmux**. On Windows, `tmux` is optional because ClawTeam defaults to the `subprocess` backend.
  115. **Check what you already have:**
  116. ```bash
  117. python --version # Need 3.10+
  118. tmux -V # Linux/macOS/WSL only
  119. openclaw --version # Or: claude --version / codex --version
  120. ```
  121. **Install missing prerequisites:**
  122. | Tool | Windows | macOS | Ubuntu/Debian |
  123. |------|---------|-------|---------------|
  124. | Python 3.10+ | Install from [python.org](https://www.python.org/downloads/windows/) | `brew install python@3.12` | `sudo apt update && sudo apt install python3 python3-pip` |
  125. | tmux | Optional | `brew install tmux` | `sudo apt install tmux` |
  126. | OpenClaw | `pip install openclaw` | `pip install openclaw` | `pip install openclaw` |
  127. > If using Claude Code or Codex instead of OpenClaw, install those per their own docs. OpenClaw is the default but not strictly required.
  128. On Windows, after installation you can verify the backend choice with:
  129. ```powershell
  130. clawteam config get default_backend
  131. ```
  132. ### Windows Native Setup
  133. Use this path for PowerShell or Windows Terminal:
  134. ```powershell
  135. py -3 -m pip install -e .
  136. clawteam config get default_backend # should print subprocess
  137. clawteam spawn --team demo --agent-name worker1 --task "Do work"
  138. clawteam board serve --port 8080
  139. ```
  140. If you want the full tmux experience, install and run ClawTeam inside WSL instead.
  141. ### Step 2: Install ClawTeam
  142. > **⚠️ Do NOT run `pip install clawteam` or `npm install -g clawteam` directly:**
  143. > - `pip install clawteam` installs the upstream PyPI version, which defaults to `claude` and lacks OpenClaw adaptations.
  144. > - `npm install -g clawteam` installs an unrelated name-squatting package (by `a9logic`). If `clawteam --version` shows "Coming Soon", you have the wrong one — run `npm uninstall -g clawteam`.
  145. >
  146. > **Use the three commands below — the `pip install -e .` step is required. It installs from the local repo, not from PyPI.**
  147. ```bash
  148. git clone https://github.com/win4r/ClawTeam-OpenClaw.git
  149. cd ClawTeam-OpenClaw
  150. pip install -e . # ← Required! Installs from local repo, NOT the same as pip install clawteam
  151. ```
  152. Optional — P2P transport (ZeroMQ):
  153. ```bash
  154. python -m pip install -e ".[p2p]"
  155. ```
  156. ### Step 3: Ensure `clawteam` is on PATH
  157. Spawned agents run in fresh shells that may not have pip's bin directory in PATH. A symlink in `~/bin` ensures `clawteam` is always reachable:
  158. ```bash
  159. mkdir -p ~/bin
  160. ln -sf "$(which clawteam)" ~/bin/clawteam
  161. ```
  162. If `which clawteam` returns nothing, find the binary manually:
  163. ```bash
  164. # Common locations:
  165. # ~/.local/bin/clawteam
  166. # /opt/homebrew/bin/clawteam
  167. # /usr/local/bin/clawteam
  168. # /Library/Frameworks/Python.framework/Versions/3.*/bin/clawteam
  169. find / -name clawteam -type f 2>/dev/null | head -5
  170. ```
  171. Then ensure `~/bin` is in your PATH — add this to `~/.zshrc` or `~/.bashrc` if it isn't:
  172. ```bash
  173. export PATH="$HOME/bin:$PATH"
  174. ```
  175. On native Windows, you usually do not need the `~/bin` symlink step. Instead, make sure the Python `Scripts` directory containing `clawteam.exe` is on `PATH`, or activate the virtual environment where you installed ClawTeam before spawning agents.
  176. ### Step 4: Install the OpenClaw skill (OpenClaw users only)
  177. The skill file teaches OpenClaw agents how to use ClawTeam through natural language. Skip this step if you're not using OpenClaw.
  178. ```bash
  179. mkdir -p ~/.openclaw/workspace/skills/clawteam
  180. cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md
  181. ```
  182. ### Step 5: Configure exec approvals (OpenClaw users only)
  183. Spawned OpenClaw agents need permission to run `clawteam` commands. Without this, agents will block on interactive permission prompts.
  184. ```bash
  185. # Ensure security mode is "allowlist" (not "full")
  186. python3 -c "
  187. import json, pathlib
  188. p = pathlib.Path.home() / '.openclaw' / 'exec-approvals.json'
  189. if p.exists():
  190. d = json.loads(p.read_text())
  191. d.setdefault('defaults', {})['security'] = 'allowlist'
  192. p.write_text(json.dumps(d, indent=2))
  193. print('exec-approvals.json updated: security = allowlist')
  194. else:
  195. print('exec-approvals.json not found — run openclaw once first, then re-run this step')
  196. "
  197. # Add clawteam to the allowlist (use the absolute path — OpenClaw 4.2+ requires it)
  198. openclaw approvals allowlist add --agent "*" "$(which clawteam)"
  199. ```
  200. > If `openclaw approvals` fails, the OpenClaw gateway may not be running. Start it first, then retry.
  201. ### Step 5b: Install the Hermes skill (Hermes Agent users only)
  202. The skill file teaches Hermes Agent how to use ClawTeam through natural language -- including when to route to clawteam (vs `delegate_task`), correct spawn flags, and timing expectations. Skip this step if you're not using Hermes.
  203. ```bash
  204. mkdir -p ~/.hermes/skills/openclaw-imports/clawteam
  205. cp skills/hermes/SKILL.md ~/.hermes/skills/openclaw-imports/clawteam/SKILL.md
  206. ```
  207. > Verify with `hermes skills list | grep clawteam`. The skill should show up under `openclaw-imports` (Hermes auto-routes skills from that directory).
  208. **Key things the skill teaches Hermes:**
  209. - Route multi-agent/swarm/team queries to clawteam (not `delegate_task`)
  210. - Use `--team-name` (not `--team`), `-g`/`--goal`, `--force` on `launch`
  211. - Always pass `--command hermes` on `launch` -- templates default to `openclaw`
  212. - On `spawn`, pass `hermes` as a trailing positional arg (not `--command hermes`)
  213. - Wait `sleep 60` after launch for worker boot, then poll the board every 30s
  214. - Never peek inboxes within the first 60s (they'll be empty)
  215. - Read inboxes and produce a consolidated report before `clawteam team cleanup`
  216. Spawned Hermes workers automatically inherit MCP servers configured in `~/.hermes/config.yaml`, so any knowledge brain or tool setup is available to every worker.
  217. ### Step 6: Verify
  218. ```bash
  219. clawteam --version # Should print version
  220. clawteam config health # Should show all green
  221. ```
  222. If using OpenClaw, also verify the skill is loaded:
  223. ```bash
  224. openclaw skills list | grep clawteam
  225. ```
  226. ### Automated installer
  227. Steps 2–6 above are also available as a single script:
  228. ```bash
  229. git clone https://github.com/win4r/ClawTeam-OpenClaw.git
  230. cd ClawTeam-OpenClaw
  231. bash scripts/install-openclaw.sh
  232. ```
  233. This script is intended for Linux, macOS, and WSL shells, not native PowerShell.
  234. ### Troubleshooting
  235. | Problem | Cause | Fix |
  236. |---------|-------|-----|
  237. | `clawteam: command not found` | pip bin dir not in PATH | Run Step 3 and ensure either `~/bin` or your Python `Scripts` directory is on PATH |
  238. | Spawned agents can't find `clawteam` | Agents run in fresh shells without pip PATH | Verify `clawteam` is on PATH in new shells; on Windows check the Python `Scripts` directory or active virtualenv |
  239. | `openclaw approvals` fails | Gateway not running | Start `openclaw gateway` first, then retry Step 5 |
  240. | `exec-approvals.json not found` | OpenClaw never ran | Run `openclaw` once to generate config, then retry Step 5 |
  241. | Agents block on permission prompts | Exec approvals security is "full" | Run Step 5 to switch to "allowlist" |
  242. | `pip install -e .` fails | Missing build deps | Run `pip install hatchling` first |
  243. | `clawteam --version` shows "Coming Soon" | Installed the npm name-squatting package (`a9logic`, unrelated to this project) | `npm uninstall -g clawteam`, then reinstall per Step 2 |
  244. ---
  245. ## Use Cases
  246. ### 1. Autonomous ML Research — 8 Agents x 8 GPUs
  247. Based on [@karpathy/autoresearch](https://github.com/karpathy/autoresearch). One prompt launches 8 research agents across H100s that design 2000+ experiments autonomously.
  248. ```
  249. Human: "Use 8 GPUs to optimize train.py. Read program.md for instructions."
  250. Leader agent:
  251. ├── Spawns 8 agents, each assigned a research direction (depth, width, LR, batch size...)
  252. ├── Each agent gets its own git worktree for isolated experiments
  253. ├── Every 30 min: checks results, cross-pollinates best configs to new agents
  254. ├── Reassigns GPUs as agents finish — fresh agents start from best known config
  255. └── Result: val_bpb 1.044 → 0.977 (6.4% improvement) across 2430 experiments in ~30 GPU-hours
  256. ```
  257. Full results: [novix-science/autoresearch](https://github.com/novix-science/autoresearch)
  258. ### 2. Agentic Software Engineering
  259. ```
  260. Human: "Build a full-stack todo app with auth, database, and React frontend."
  261. Leader agent:
  262. ├── Creates tasks with dependency chains (API schema → auth + DB → frontend → tests)
  263. ├── Spawns 5 agents (architect, 2 backend, frontend, tester) in separate worktrees
  264. ├── Dependencies auto-resolve: architect completes → backend unblocks → tester unblocks
  265. ├── Agents coordinate via inbox: "Here's the OpenAPI spec", "Auth endpoints ready"
  266. └── Leader merges all worktrees into main when complete
  267. ```
  268. ### 3. AI Hedge Fund — Template Launch
  269. A TOML template spawns a complete 7-agent investment team with one command:
  270. ```bash
  271. clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"
  272. ```
  273. Seven agents total: 5 analysts (value, growth, technical, fundamentals, sentiment) work in parallel, a risk manager synthesizes all signals, and a portfolio manager makes the final decision.
  274. Templates are TOML files — **create your own** for any domain.
  275. ---
  276. ## Features
  277. <table>
  278. <tr>
  279. <td width="50%">
  280. ### Agent Self-Organization
  281. - Leader spawns and manages workers
  282. - Auto-injected coordination prompt — zero manual setup
  283. - Workers self-report status and idle state
  284. - Any CLI agent can participate
  285. ### Workspace Isolation
  286. - Each agent gets its own **git worktree**
  287. - No merge conflicts between parallel agents
  288. - Checkpoint, merge, and cleanup commands
  289. - Branch naming: `clawteam/{team}/{agent}`
  290. ### Task Tracking with Dependencies
  291. - Shared kanban: `pending` → `in_progress` → `completed` / `blocked`
  292. - `--blocked-by` chains with auto-unblock on completion
  293. - `task wait` blocks until all tasks complete
  294. </td>
  295. <td width="50%">
  296. ### Inter-Agent Messaging
  297. - Point-to-point inboxes (send, receive, peek)
  298. - Broadcast to all team members
  299. - File-based (default) or ZeroMQ P2P transport
  300. ### Monitoring & Dashboards
  301. - `board show` — terminal kanban
  302. - `board live` — auto-refreshing dashboard
  303. - `board attach` — tiled tmux view of all agents (Linux/macOS/WSL)
  304. - `board serve` — Web UI with real-time updates
  305. ### Team Templates
  306. - TOML files define team archetypes (roles, tasks, prompts)
  307. - One command: `clawteam launch <template>`
  308. - Variable substitution: `{goal}`, `{team_name}`, `{agent_name}`
  309. </td>
  310. </tr>
  311. </table>
  312. ### v0.3.0 — Production Intelligence *(New)*
  313. - **Hermes Agent Support** — native spawn target across NativeCliAdapter, tmux, and subprocess backends. Auto-inserts `chat` subcommand and passes `--source tool` (session hygiene requires the upstream Hermes patch described in `skills/hermes/SKILL.md` — ClawTeam passes the flag correctly; Hermes ≤ 0.8.0 ignores it).
  314. - **Cost Dashboard** — real-time token/cost by agent, model, and task (`clawteam board cost`). No competitor has this.
  315. - **Circuit Breaker** — healthy → degraded → open tri-state with half-open probing
  316. - **Retry with Backoff** — `spawn_with_retry()` for resilient agent spawning
  317. - **Idempotency Keys** — deduplication for `create()` and `send()`
  318. - **Intent-Based Prompts** — military C2 Auftragstaktik: agents get `intent` + `end_state` + `constraints`
  319. - **Boids Emergence Rules** — Reynolds 1986 flocking rules adapted for LLM agents
  320. - **Metacognitive Self-Assessment** — agents tag their own confidence levels
  321. - **Per-Agent Model Resolution** — 7-level priority chain, mix Claude/GPT/Qwen in one team
  322. - **Runtime Live Injection** — `runtime inject/state/watch` for messaging running agents
  323. **Also:** plan approval workflows, graceful lifecycle management, `--json` output on all commands, cross-machine support (NFS/SSHFS or P2P), multi-user namespacing, spawn validation with auto-rollback, `fcntl` file locking for concurrent safety.
  324. ---
  325. ## OpenClaw Integration
  326. This fork makes [OpenClaw](https://openclaw.ai) the **default agent**. Without ClawTeam, each OpenClaw agent works in isolation. ClawTeam transforms it into a multi-agent platform.
  327. | Capability | OpenClaw Alone | OpenClaw + ClawTeam |
  328. |-----------|---------------|-------------------|
  329. | **Task assignment** | Manual per-agent messaging | Leader autonomously splits, assigns, monitors |
  330. | **Parallel development** | Shared working directory | Isolated git worktrees per agent |
  331. | **Dependencies** | Manual polling | `--blocked-by` with auto-unblock |
  332. | **Communication** | Only through AGI relay | Direct point-to-point inbox + broadcast |
  333. | **Observability** | Read logs | Kanban board + tiled tmux view |
  334. Once the skill is installed, talk to your OpenClaw bot in any channel:
  335. | What you say | What happens |
  336. |-------------|-------------|
  337. | "Create a 5-agent team to build a web app" | Creates team, tasks, and spawns 5 agents with the configured backend |
  338. | "Launch a hedge-fund analysis team" | `clawteam launch hedge-fund` with 7 agents |
  339. | "Check the status of my agent team" | `clawteam board show` with kanban output |
  340. ```
  341. You (Telegram/Discord/TUI)
  342. │
  343. ▼
  344. ┌──────────────────┐
  345. │ OpenClaw Gateway │ ← activates clawteam skill
  346. └────────┬─────────┘
  347. │
  348. ▼
  349. ┌──────────────────┐ clawteam spawn ┌─────────────────┐
  350. │ Leader Agent │ ─────────────────────► │ openclaw tui │
  351. │ (openclaw) │ ──┐ │ (tmux window) │
  352. │ │ │ │ git worktree │
  353. │ Manages swarm │ ├──────────────────► ├─────────────────┤
  354. │ via clawteam │ │ │ openclaw tui │
  355. │ CLI │ ├──────────────────► ├─────────────────┤
  356. └──────────────────┘ │ │ openclaw tui │
  357. └──────────────────► └─────────────────┘
  358. All coordinate via
  359. ~/.clawteam/ (tasks, inboxes)
  360. ```
  361. ---
  362. ## Hermes Agent Integration
  363. ClawTeam ships first-class support for [Hermes Agent](https://github.com/NousResearch/hermes-agent) — Nous Research's self-improving CLI agent. Hermes workers spawn via the same adapter path as OpenClaw (tmux or subprocess), but use Hermes-native command flags (`hermes chat --yolo --source tool -q "<task>"`).
  364. Hermes workers automatically inherit any MCP servers configured in `~/.hermes/config.yaml`, so whatever tools you've wired into Hermes are available to every spawned worker.
  365. | Capability | Hermes Alone | Hermes + ClawTeam |
  366. |-----------|--------------|-------------------|
  367. | **Parallelism** | Single session | Spawn N workers in tmux windows |
  368. | **Coordination** | Manual | Kanban + inboxes + task dependencies |
  369. | **Isolation** | Shared working dir | Git worktrees per agent |
  370. | **Session hygiene** | Mixes with user sessions | `--source tool` tag passed to Hermes (requires upstream fix — see SKILL.md `Known upstream issues`) |
  371. **Using Hermes with ClawTeam:**
  372. All built-in templates (`hedge-fund`, `research-paper`, `code-review`, `strategy-room`) default to spawning OpenClaw workers. Hermes users pass `--command hermes` to override:
  373. ```bash
  374. clawteam launch hedge-fund --team-name <name> --goal "..." --command hermes --force
  375. ```
  376. Or spawn manually, passing `hermes` as the trailing positional argument:
  377. ```bash
  378. clawteam spawn --team <team> --agent-name <name> --task "..." --no-workspace hermes
  379. ```
  380. Note: the built-in templates were designed around OpenClaw's `clawteam inbox send` coordination pattern. Hermes workers sometimes complete their analysis without executing the inbox-send command. If `clawteam inbox peek` returns empty while the kanban shows `COMPLETED`, capture tmux scrollback directly:
  381. ```bash
  382. tmux capture-pane -t clawteam-<team>:<window-index> -p -S -500
  383. ```
  384. **Installation:** see Step 5b in the Install section.
  385. ---
  386. ## Architecture
  387. ```
  388. Human: "Optimize this LLM"
  389. │
  390. ▼
  391. ┌──────────────┐ clawteam spawn ┌──────────────┐
  392. │ Leader │ ──────────────────────► │ Worker │
  393. │ (any agent) │ ──────┐ │ git worktree │
  394. │ │ ├──────────────► │ tmux window │
  395. │ spawn │ │ ├──────────────┤
  396. │ task create │ ├──────────────► │ Worker │
  397. │ inbox send │ │ │ git worktree │
  398. │ board show │ └──────────────► │ tmux window │
  399. └──────────────┘ └──────────────┘
  400. │
  401. ▼
  402. ┌─────────────────────┐
  403. │ ~/.clawteam/ │
  404. │ ├── teams/ (who) │
  405. │ ├── tasks/ (what)│
  406. │ ├── inboxes/ (talk)│
  407. │ └── workspaces/ │
  408. └─────────────────────┘
  409. ```
  410. All state lives in `~/.clawteam/` as JSON files. No database, no server. Atomic writes with cross-platform file locking ensure crash safety.
  411. | Setting | Env Var | Default |
  412. |---------|---------|---------|
  413. | Data directory | `CLAWTEAM_DATA_DIR` | `~/.clawteam` |
  414. | Transport | `CLAWTEAM_TRANSPORT` | `file` |
  415. | Workspace mode | `CLAWTEAM_WORKSPACE` | `auto` |
  416. | Spawn backend | `CLAWTEAM_DEFAULT_BACKEND` | `tmux` on Linux/macOS, `subprocess` on Windows |
  417. ---
  418. ## Command Reference
  419. <details open>
  420. <summary><strong>Core Commands</strong></summary>
  421. ```bash
  422. # Team lifecycle
  423. clawteam team spawn-team <team> -d "description" -n <leader>
  424. clawteam team discover # List all teams
  425. clawteam team status <team> # Show members
  426. clawteam team cleanup <team> --force # Delete team
  427. # Spawn agents (note: `spawn` uses --team; `launch` uses --team-name)
  428. clawteam spawn --team <team> --agent-name <name> --task "do this"
  429. clawteam spawn codex --team <team> --agent-name <name> --task "do this"
  430. clawteam spawn --team <team> --agent-name <name> --task "do this" hermes
  431. clawteam spawn subprocess hermes --team <team> --agent-name <name> --task "do this"
  432. # Task management
  433. clawteam task create <team> "subject" -o <owner> --blocked-by <id1>,<id2>
  434. clawteam task update <team> <id> --status completed # auto-unblocks dependents
  435. clawteam task list <team> --status blocked --owner worker1
  436. clawteam task wait <team> --timeout 300
  437. # Messaging
  438. clawteam inbox send <team> <to> "message"
  439. clawteam inbox broadcast <team> "message"
  440. clawteam inbox receive <team> # consume messages
  441. clawteam inbox peek <team> # read without consuming
  442. # Monitoring
  443. clawteam board show <team> # terminal kanban
  444. clawteam board live <team> --interval 3 # auto-refresh
  445. clawteam board attach <team> # tiled tmux view (Linux/macOS/WSL)
  446. clawteam board serve --port 8080 # web UI
  447. ```
  448. </details>
  449. <details>
  450. <summary><strong>Workspace, Plan, Lifecycle, Config</strong></summary>
  451. ```bash
  452. # Workspace (git worktree management)
  453. clawteam workspace list <team>
  454. clawteam workspace checkpoint <team> <agent> # auto-commit
  455. clawteam workspace merge <team> <agent> # merge back to main
  456. clawteam workspace cleanup <team> <agent> # remove worktree
  457. # Plan approval
  458. clawteam plan submit <team> <agent> "plan" --summary "TL;DR"
  459. clawteam plan approve <team> <plan-id> <agent> --feedback "LGTM"
  460. clawteam plan reject <team> <plan-id> <agent> --feedback "Revise X"
  461. # Lifecycle
  462. clawteam lifecycle request-shutdown <team> <agent> --reason "done"
  463. clawteam lifecycle approve-shutdown <team> <request-id> <agent>
  464. clawteam lifecycle idle <team>
  465. # Templates
  466. clawteam launch <template> --team <name> --goal "Build X"
  467. clawteam template list
  468. # Config
  469. clawteam config show
  470. clawteam config set transport p2p
  471. clawteam config health
  472. ```
  473. </details>
  474. ---
  475. ## Per-Agent Model Assignment
  476. Assign different models to different agent roles for better cost/performance tradeoffs in multi-agent swarms. Uses a **7-level priority chain**: CLI > agent model > agent tier > template strategy > template model > config default > None.
  477. **Per-agent model in templates:**
  478. ```toml
  479. [template]
  480. name = "my-team"
  481. command = ["openclaw"]
  482. model = "sonnet-4.6" # default for all agents
  483. model_strategy = "auto" # or: leaders→strong, workers→balanced
  484. [template.leader]
  485. name = "lead"
  486. model = "opus" # override for leader
  487. [[template.agents]]
  488. name = "worker"
  489. model_tier = "cheap" # cost tiers: strong / balanced / cheap
  490. ```
  491. **CLI flags:**
  492. ```bash
  493. clawteam spawn --model opus # single agent
  494. clawteam launch my-template --model gpt-5.4 # override all agents
  495. clawteam launch my-template --model-strategy auto # auto-assign by role
  496. ```
  497. ---
  498. ## Roadmap
  499. | Version | What | Status |
  500. |---------|------|--------|
  501. | v0.2 | OpenClaw default agent, workspace overlay, zombie detection, 11-language README | Shipped |
  502. | v0.3 | Research-backed intelligence, cost dashboard, circuit breaker, per-agent models, runtime injection | **Shipped** |
  503. | v0.4 | Windows full support, A2A Gateway integration | In Progress |
  504. | v0.5 | Agent template marketplace — community-contributed TOML templates | Planned |
  505. | v0.6 | Memory deep integration — per-team/per-task knowledge sharing | Planned |
  506. | v1.0 | Production-grade — auth, permissions, audit logs | Exploring |
  507. ---
  508. ## Contributing
  509. We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, code style, and PR guidelines.
  510. Areas we'd love help with:
  511. - **Agent integrations** — support for more CLI agents
  512. - **Team templates** — TOML templates for new domains
  513. - **Transport backends** — Redis, NATS, etc.
  514. - **Dashboard improvements** — Web UI, Grafana
  515. - **Documentation** — tutorials and best practices
  516. ---
  517. ## Acknowledgements
  518. - [@karpathy/autoresearch](https://github.com/karpathy/autoresearch) — autonomous ML research framework
  519. - [OpenClaw](https://openclaw.ai) — default agent backend
  520. - [Hermes Agent](https://github.com/NousResearch/hermes-agent) — Nous Research's self-improving CLI agent
  521. - [Claude Code](https://claude.ai/claude-code) and [Codex](https://openai.com/codex) — supported AI coding agents
  522. - [ai-hedge-fund](https://github.com/virattt/ai-hedge-fund) — hedge fund template inspiration
  523. - [CLI-Anything](https://github.com/HKUDS/CLI-Anything) — sister project
  524. ## License
  525. MIT — free to use, modify, and distribute.
  526. ---
  527. <div align="center">
  528. **ClawTeam** — *Agent Swarm Intelligence.*
  529. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

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