clawteam

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:

# Stock analysis (7 specialist analysts: portfolio-manager, buffett, growth, technical, fundamentals, sentiment, risk-manager)
clawteam launch hedge-fund --team-name tesla --goal "Analyze TSLA" --command hermes --force

# Research paper summary
clawteam launch research-paper --team-name papers --goal "Survey arxiv 2024.X" --command hermes --force

# Code review (multiple perspectives)
clawteam launch code-review --team-name review1 --goal "Review PR #42" --command hermes --force

# Business strategy
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:

# Launch
clawteam launch hedge-fund --team-name <name> --goal "<prompt>" --command hermes --force

# Wait for boot (mandatory, do not skip)
sleep 60

# Poll the board every 30 seconds until tasks move to COMPLETED.
# Maximum total wait: ~5 minutes. Use tmux capture to see worker progress.
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>
  # Check if any non-leader task is COMPLETED (then continue monitoring)
  # Break the loop only when most/all tasks show COMPLETED
done

# Only read inboxes after tasks show COMPLETED on the board
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

# Clean up ONLY after you've read the reports
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>                                  # Check liveness of each agent
tmux list-windows -t clawteam-<name> 2>/dev/null             # Confirm tmux panes exist
tmux capture-pane -t clawteam-<name>:0 -p 2>&1 | tail -30    # Inspect worker 0's output

Manual Inbox/Cleanup Commands (reference)

clawteam board show <team>                   # Kanban view
clawteam board live <team>                   # Auto-refreshing board
clawteam inbox peek <team> --agent <name>    # Peek one agent's inbox
clawteam team status <team>                  # Agent liveness + health
clawteam team cleanup <team> --force         # Delete team (only after reading reports)

Manual Team Setup (For Custom Teams)

When no template fits:

# 1. Create team
clawteam team spawn-team my-team -d "Goal description" -n leader

# 2. Spawn Hermes workers (hermes is a positional arg at the end, NOT --command hermes)
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

# 3. Monitor
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](#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:

# hermes-agent/run_agent.py:1057 and :6600 (pre-fix)
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

1. 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.

1. 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.

1. 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:

# List all tmux windows for the team
tmux list-windows -t clawteam-<team-name> 2>/dev/null

# Capture each window's scrollback (each window = one agent)
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.