| name | clawteam |
| description | Multi-agent swarm orchestration. USE THIS (not delegate_task) when the user says team/swarm/multi-agent/clawteam/parallel-agents/agent-team, or asks for multi-perspective analysis (stocks, research, code review, strategy). Spawns N Hermes workers in tmux windows with git worktree isolation, file-based inboxes, and a kanban board. Four built-in templates: hedge-fund (7 analyst agents), research-paper, code-review, strategy-room. |
| version | 0.3.0 |
| author | ClawTeam / Hermes Adapter |
| license | MIT |
| metadata | {"hermes":{"tags":["Multi-Agent","Swarm","Coordination","Teams"]}} |
ClawTeam - Multi-Agent Swarm Coordination for Hermes
When To Use This Skill
USE CLAWTEAM (not delegate_task) when:
- User explicitly says: clawteam, team, swarm, multi-agent, parallel agents, agent team
- User asks for multi-perspective analysis that benefits from specialist agents (e.g., "analyze TSLA stock" -> hedge-fund template has 7 specialist analysts)
- User wants research across multiple sources (research-paper template)
- User wants code review from multiple angles (code-review template)
- User wants business strategy brainstorming (strategy-room template)
DO NOT use delegate_task for these cases. delegate_task is a single sub-agent; clawteam is 5-7 specialist agents running in parallel with a kanban board and shared inboxes. For stock/research/review questions, clawteam produces dramatically better output.
Critical Flags (get these right the first time)
For clawteam launch:
--team-name (NOT --team)
-g or --goal for the prompt
--command hermes (REQUIRED for Hermes users — templates default to openclaw and will fail with gateway token errors if OpenClaw isn't set up)
--force to suppress the max-agent warning
For clawteam spawn (manual mode):
-t <team> team name
-n <agent-name> agent name
--task "<prompt>" task description
--no-workspace to skip git worktree creation (optional)
- Trailing positional arg:
hermes (NOT --command hermes)
Launch a Template (Recommended Path)
All built-in templates default to command = ["openclaw"]. Hermes users MUST pass --command hermes:
clawteam launch hedge-fund --team-name tesla --goal "Analyze TSLA" --command hermes --force
clawteam launch research-paper --team-name papers --goal "Survey arxiv 2024.X" --command hermes --force
clawteam launch code-review --team-name review1 --goal "Review PR #42" --command hermes --force
clawteam launch strategy-room --team-name strat --goal "Q2 planning" --command hermes --force
CRITICAL: Timing Expectations (DO NOT cleanup early)
Spawned Hermes workers need substantial time to produce output:
- Boot: 20-40 seconds per worker (loading 62 tools + 113 skills + MCP servers)
- Research/analysis: 1-5 minutes depending on task complexity
- Hedge-fund template (7 analysts running in parallel): typically 2-5 minutes total
After launching a team, WAIT before checking results. NEVER check inboxes within the first 60 seconds — they will be empty and you will incorrectly conclude the team failed.
Correct polling pattern for a hedge-fund team:
clawteam launch hedge-fund --team-name <name> --goal "<prompt>" --command hermes --force
sleep 60
for i in 1 2 3 4 5 6 7 8; do
sleep 30
echo "=== tick $i ($(( i * 30 + 60 ))s elapsed) ==="
clawteam board show <name>
done
for agent in portfolio-manager buffett-analyst growth-analyst technical-analyst fundamentals-analyst sentiment-analyst risk-manager; do
echo "=== $agent ==="
clawteam inbox peek <name> --agent $agent
done
clawteam team cleanup <name> --force
If inboxes are still empty after 5 minutes, something is wrong (token auth, model provider, or worker crashed). Inspect instead of giving up:
clawteam team status <name>
tmux list-windows -t clawteam-<name> 2>/dev/null
tmux capture-pane -t clawteam-<name>:0 -p 2>&1 | tail -30
Manual Inbox/Cleanup Commands (reference)
clawteam board show <team>
clawteam board live <team>
clawteam inbox peek <team> --agent <name>
clawteam team status <team>
clawteam team cleanup <team> --force
Manual Team Setup (For Custom Teams)
When no template fits:
clawteam team spawn-team my-team -d "Goal description" -n leader
clawteam spawn -t my-team -n researcher --task "Research X" --no-workspace hermes
clawteam spawn -t my-team -n writer --task "Write report based on researcher's findings" --no-workspace hermes
clawteam board show my-team
How The Hermes Adapter Builds Commands
When ClawTeam spawns a Hermes worker, the adapter builds:
hermes chat --yolo --source tool -q "<task prompt>"
Notes on each flag:
chat subcommand inserted only if user passed bare hermes
--yolo when skip_permissions=True (default for clawteam)
--source tool is intended to tag the session so clawteam spawns don't clutter hermes sessions list. Known limitation on Hermes ≤ 0.8.0: the flag is accepted but not propagated to the SQLite store — sessions still record as source=cli. ClawTeam passes the flag correctly; the fix belongs upstream (run_agent.py:1057 and :6600 short-circuit on self.platform="cli" before reading HERMES_SESSION_SOURCE). See Known upstream issues below for the one-line patch.
-q "<prompt>" passes the task as a one-shot query
- No
--continue — Hermes auto-generates a fresh session ID per spawn
-m <model> added if --model was passed to clawteam
Known upstream issues
--source tool ignored by Hermes ≤ 0.8.0
Hermes's cmd_chat correctly sets HERMES_SESSION_SOURCE from the flag, but the agent constructor's session-create call reads self.platform first:
source=self.platform or os.environ.get("HERMES_SESSION_SOURCE", "cli"),
cli.py hardcodes platform="cli", which is truthy, so the env var never wins. One-line fix (swap the precedence):
source=os.environ.get("HERMES_SESSION_SOURCE") or self.platform or "cli",
Verify post-fix with: hermes chat --yolo --source tool -q "ping" && hermes sessions list --source tool. Until this lands upstream, ClawTeam-spawned Hermes workers appear interleaved with your interactive sessions — annoying, not broken.
MCP Inheritance
Spawned Hermes workers inherit any MCP servers configured in ~/.hermes/config.yaml. If you have a knowledge base, memory store, or other MCP tool wired into Hermes, every worker gets that capability automatically.
Include MCP-related instructions in task prompts if you want workers to use them:
clawteam spawn -t research -n analyst --task "Research topic X. Use available MCP tools to check prior work and store findings." --no-workspace hermes
Command Reference
Team Management
| Command | Description |
|---|
clawteam team spawn-team <name> -d "<desc>" -n <leader> | Create team |
clawteam team discover | List all teams |
clawteam team status <team> | Show team status |
clawteam team cleanup <team> --force | Delete team |
Launching Templates
| Command | Description |
|---|
clawteam launch <template> --team-name <name> --goal "<prompt>" --command hermes --force | One-command team launch |
clawteam template list | List available templates |
Spawning Agents Manually
| Command | Description |
|---|
clawteam spawn -t <team> -n <name> --task "<prompt>" hermes | Spawn Hermes worker |
clawteam spawn -t <team> -n <name> --task "<prompt>" --skip-permissions hermes | Spawn with --yolo |
clawteam spawn -t <team> -n <name> --task "<prompt>" -m claude-sonnet-4 hermes | Spawn with specific model |
Task Management
| Command | Description |
|---|
clawteam task create <team> "<desc>" -o <owner> | Create task |
clawteam task create <team> "<desc>" -o <owner> --blocked-by <id> | Create with dependency |
clawteam task update <team> <id> --status completed | Complete task |
clawteam task list <team> | List all tasks |
Messaging
| Command | Description |
|---|
clawteam msg send <team> --from <name> --to <name> "<msg>" | Direct message |
clawteam msg broadcast <team> --from <name> "<msg>" | Broadcast to all |
clawteam inbox peek <team> --agent <name> | Peek at inbox |
clawteam inbox receive <team> | Drain your own inbox |
Monitoring
| Command | Description |
|---|
clawteam board show <team> | Kanban board |
clawteam board attach <team> | Tmux tiled view (requires terminal) |
clawteam board live <team> | Auto-refreshing board |
clawteam board serve --port 8080 | Web dashboard |
Known Failure Modes
-
risk-manager crash: The risk-manager agent is prone to crashing mid-execution ("Agent 'risk-manager' exited unexpectedly. Reset N task(s) to pending"). This can leave the team's final synthesis incomplete. If this happens, read tmux scrollback for the portfolio-manager (leader) window first — it may have the final recommendation before the crash.
-
Inbox empty despite COMPLETED tasks: Hermes workers write to tmux scrollback, not to the inbox system. The kanban board reflects task state but not content. Always capture tmux panes to read actual output.
-
Workers do not persist findings: Agent outputs live in tmux scrollback and are lost when the session is cleaned up. Capture the panes before running team cleanup, or instruct agents (via the task prompt) to write to any MCP-backed persistence store configured in ~/.hermes/config.yaml.
CRITICAL: Inbox Peek Is Unreliable — Use Tmux Capture
clawteam inbox peek often returns EMPTY even when tasks show COMPLETED on the board. The actual agent outputs live in tmux scrollback, not in the inbox system.
Always use tmux pane capture to read agent reports:
tmux list-windows -t clawteam-<team-name> 2>/dev/null
for win in $(tmux list-windows -t clawteam-<team-name> -F '#{window_index}' 2>/dev/null); do
echo -e "\n\n=== Window $win ==="
tmux capture-pane -t clawteam-<team-name>:$win -p 2>&1 | tail -100
done
Also: If you have an MCP-backed persistence store (knowledge base, memory system) wired into ~/.hermes/config.yaml, include instructions in the goal so agents write findings there. This gives you a persistent fallback when tmux sessions are lost. Exact tool names depend on which MCP server you use.
Anti-Patterns (Do Not Do)
- Don't use
delegate_task when the user asks for multi-agent/swarm/team analysis. Use clawteam.
- Don't pass
--team (the flag is --team-name).
- Don't pass
--command hermes to spawn (it's a positional arg at the end). That flag only works on launch.
- Don't forget
--command hermes on launch — templates default to openclaw.
- Don't assume templates will use Hermes by default. They don't. Always pass
--command hermes.
- Don't clean up the team before reading final reports — BUT
inbox peek alone is unreliable; always ALSO capture tmux panes.
- Don't rely on
clawteam inbox peek alone — tasks can be COMPLETED on the board while inbox messages are empty. Tmux scrollback capture is the source of truth.