ClawTeam-OpenClaw clawteam

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.

install

source · Clone the upstream repo

git clone https://github.com/win4r/ClawTeam-OpenClaw

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/win4r/ClawTeam-OpenClaw "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/hermes" ~/.claude/skills/win4r-clawteam-openclaw-clawteam && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/win4r/ClawTeam-OpenClaw "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/hermes" ~/.openclaw/skills/win4r-clawteam-openclaw-clawteam && rm -rf "$T"

manifest: skills/hermes/SKILL.md

source content

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

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:

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