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

- Skill: `win4r/clawteam` (Agent Skill)
- Install (CLI): `npx skillmds@latest add win4r/clawteam`
- Raw SKILL.md: https://api.skillmd.com/api/skills/win4r/clawteam/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: win4r (https://skillmd.com/u/win4r)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/win4r/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`:

```bash
# 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:

```bash
# 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:

```bash
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)

```bash
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:

```bash
# 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:

```python
# 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):

```python
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:
```bash
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.

2. **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.

3. **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:**

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