Skip to content

win4r/ClawTeam-OpenClaw

Repository files navigation

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Français | Español | Deutsch | Italiano | Русский | Português (Brasil)

🦞ClawTeam-OpenClaw

Multi-agent swarm coordination for CLI coding agents — OpenClaw as default

Upstream Quick Start License

Python Agents Transport Version

Fork of 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.

You set the goal. The agent swarm handles the rest — spawning workers, splitting tasks, coordinating, and merging results.

Works with OpenClaw (default), Claude Code, Codex, Hermes Agent, nanobot, Cursor, and any CLI agent.

Platform Support

  • Linux and macOS keep the original tmux-first workflow.
  • Windows 10/11 is supported with an automatic fallback to the subprocess backend.
  • Task locking, process liveness checks, and signal registration are routed through a shared compatibility layer so unsupported Unix-only behavior degrades safely on Windows.
  • board attach still requires tmux, so on Windows prefer clawteam board serve for live monitoring.
  • If you want the original tmux workflow on Windows, run ClawTeam inside WSL.

Why ClawTeam?

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.

ClawTeam Other multi-agent frameworks
Who uses it The AI agents themselves Humans writing orchestration code
Setup pip install + one prompt Docker, cloud APIs, YAML configs
Infrastructure Filesystem + tmux Redis, message queues, databases
Agent support Any CLI agent Framework-specific only
Isolation Git worktrees (real branches) Containers or virtual envs

How It Works

Agents Spawn Agents

The leader calls clawteam spawn to create workers. Each gets its own git worktree, spawn backend session, and identity.

clawteam spawn --team my-team \
  --agent-name worker1 \
  --task "Implement auth module"

Agents Talk to Agents

Workers check inboxes, update tasks, and report results — all through CLI commands auto-injected into their prompt.

clawteam task list my-team --owner me
clawteam inbox send my-team leader \
  "Auth done. All tests passing."

You Just Watch

Monitor the swarm from a tiled tmux view or Web UI. The leader handles coordination.

clawteam board serve --port 8080
# Or, on Linux/macOS/WSL with tmux:
clawteam board attach my-team

Quick Start

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 clawteam spawn --team ... Default
Claude Code clawteam spawn claude --team ... Full support
Codex clawteam spawn codex --team ... Full support
nanobot clawteam spawn nanobot --team ... Full support
Hermes Agent clawteam spawn hermes --team ... Full support (tmux + subprocess)
Cursor clawteam spawn subprocess cursor --team ... Experimental
Custom scripts clawteam spawn subprocess python --team ... Full support

Install

Step 1: Prerequisites

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.

Check what you already have:

python --version    # Need 3.10+
tmux -V             # Linux/macOS/WSL only
openclaw --version  # Or: claude --version / codex --version

Install missing prerequisites:

Tool Windows macOS Ubuntu/Debian
Python 3.10+ Install from python.org brew install python@3.12 sudo apt update && sudo apt install python3 python3-pip
tmux Optional brew install tmux sudo apt install tmux
OpenClaw pip install openclaw pip install openclaw pip install openclaw

If using Claude Code or Codex instead of OpenClaw, install those per their own docs. OpenClaw is the default but not strictly required.

On Windows, after installation you can verify the backend choice with:

clawteam config get default_backend

Windows Native Setup

Use this path for PowerShell or Windows Terminal:

py -3 -m pip install -e .
clawteam config get default_backend   # should print subprocess
clawteam spawn --team demo --agent-name worker1 --task "Do work"
clawteam board serve --port 8080

If you want the full tmux experience, install and run ClawTeam inside WSL instead.

Step 2: Install ClawTeam

⚠️ Do NOT run pip install clawteam or npm install -g clawteam directly:

  • pip install clawteam installs the upstream PyPI version, which defaults to claude and lacks OpenClaw adaptations.
  • 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.

Use the three commands below — the pip install -e . step is required. It installs from the local repo, not from PyPI.

git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
pip install -e .    # ← Required! Installs from local repo, NOT the same as pip install clawteam

Optional — P2P transport (ZeroMQ):

python -m pip install -e ".[p2p]"

Step 3: Ensure clawteam is on PATH

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:

mkdir -p ~/bin
ln -sf "$(which clawteam)" ~/bin/clawteam

If which clawteam returns nothing, find the binary manually:

# Common locations:
# ~/.local/bin/clawteam
# /opt/homebrew/bin/clawteam
# /usr/local/bin/clawteam
# /Library/Frameworks/Python.framework/Versions/3.*/bin/clawteam
find / -name clawteam -type f 2>/dev/null | head -5

Then ensure ~/bin is in your PATH — add this to ~/.zshrc or ~/.bashrc if it isn't:

export PATH="$HOME/bin:$PATH"

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.

Step 4: Install the OpenClaw skill (OpenClaw users only)

The skill file teaches OpenClaw agents how to use ClawTeam through natural language. Skip this step if you're not using OpenClaw.

mkdir -p ~/.openclaw/workspace/skills/clawteam
cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md

Step 5: Configure exec approvals (OpenClaw users only)

Spawned OpenClaw agents need permission to run clawteam commands. Without this, agents will block on interactive permission prompts.

# Ensure security mode is "allowlist" (not "full")
python3 -c "
import json, pathlib
p = pathlib.Path.home() / '.openclaw' / 'exec-approvals.json'
if p.exists():
    d = json.loads(p.read_text())
    d.setdefault('defaults', {})['security'] = 'allowlist'
    p.write_text(json.dumps(d, indent=2))
    print('exec-approvals.json updated: security = allowlist')
else:
    print('exec-approvals.json not found — run openclaw once first, then re-run this step')
"

# Add clawteam to the allowlist (use the absolute path — OpenClaw 4.2+ requires it)
openclaw approvals allowlist add --agent "*" "$(which clawteam)"

If openclaw approvals fails, the OpenClaw gateway may not be running. Start it first, then retry.

Step 5b: Install the Hermes skill (Hermes Agent users only)

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.

mkdir -p ~/.hermes/skills/openclaw-imports/clawteam
cp skills/hermes/SKILL.md ~/.hermes/skills/openclaw-imports/clawteam/SKILL.md

Verify with hermes skills list | grep clawteam. The skill should show up under openclaw-imports (Hermes auto-routes skills from that directory).

Key things the skill teaches Hermes:

  • Route multi-agent/swarm/team queries to clawteam (not delegate_task)
  • Use --team-name (not --team), -g/--goal, --force on launch
  • Always pass --command hermes on launch -- templates default to openclaw
  • On spawn, pass hermes as a trailing positional arg (not --command hermes)
  • Wait sleep 60 after launch for worker boot, then poll the board every 30s
  • Never peek inboxes within the first 60s (they'll be empty)
  • Read inboxes and produce a consolidated report before clawteam team cleanup

Spawned Hermes workers automatically inherit MCP servers configured in ~/.hermes/config.yaml, so any knowledge brain or tool setup is available to every worker.

Step 6: Verify

clawteam --version          # Should print version
clawteam config health      # Should show all green

If using OpenClaw, also verify the skill is loaded:

openclaw skills list | grep clawteam

Automated installer

Steps 2–6 above are also available as a single script:

git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
bash scripts/install-openclaw.sh

This script is intended for Linux, macOS, and WSL shells, not native PowerShell.

Troubleshooting

Problem Cause Fix
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
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
openclaw approvals fails Gateway not running Start openclaw gateway first, then retry Step 5
exec-approvals.json not found OpenClaw never ran Run openclaw once to generate config, then retry Step 5
Agents block on permission prompts Exec approvals security is "full" Run Step 5 to switch to "allowlist"
pip install -e . fails Missing build deps Run pip install hatchling first
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

Use Cases

1. Autonomous ML Research — 8 Agents x 8 GPUs

Based on @karpathy/autoresearch. One prompt launches 8 research agents across H100s that design 2000+ experiments autonomously.

Human: "Use 8 GPUs to optimize train.py. Read program.md for instructions."

Leader agent:
├── Spawns 8 agents, each assigned a research direction (depth, width, LR, batch size...)
├── Each agent gets its own git worktree for isolated experiments
├── Every 30 min: checks results, cross-pollinates best configs to new agents
├── Reassigns GPUs as agents finish — fresh agents start from best known config
└── Result: val_bpb 1.044 → 0.977 (6.4% improvement) across 2430 experiments in ~30 GPU-hours

Full results: novix-science/autoresearch

2. Agentic Software Engineering

Human: "Build a full-stack todo app with auth, database, and React frontend."

Leader agent:
├── Creates tasks with dependency chains (API schema → auth + DB → frontend → tests)
├── Spawns 5 agents (architect, 2 backend, frontend, tester) in separate worktrees
├── Dependencies auto-resolve: architect completes → backend unblocks → tester unblocks
├── Agents coordinate via inbox: "Here's the OpenAPI spec", "Auth endpoints ready"
└── Leader merges all worktrees into main when complete

3. AI Hedge Fund — Template Launch

A TOML template spawns a complete 7-agent investment team with one command:

clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"

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.

Templates are TOML files — create your own for any domain.


Features

Agent Self-Organization

  • Leader spawns and manages workers
  • Auto-injected coordination prompt — zero manual setup
  • Workers self-report status and idle state
  • Any CLI agent can participate

Workspace Isolation

  • Each agent gets its own git worktree
  • No merge conflicts between parallel agents
  • Checkpoint, merge, and cleanup commands
  • Branch naming: clawteam/{team}/{agent}

Task Tracking with Dependencies

  • Shared kanban: pendingin_progresscompleted / blocked
  • --blocked-by chains with auto-unblock on completion
  • task wait blocks until all tasks complete

Inter-Agent Messaging

  • Point-to-point inboxes (send, receive, peek)
  • Broadcast to all team members
  • File-based (default) or ZeroMQ P2P transport

Monitoring & Dashboards

  • board show — terminal kanban
  • board live — auto-refreshing dashboard
  • board attach — tiled tmux view of all agents (Linux/macOS/WSL)
  • board serve — Web UI with real-time updates

Team Templates

  • TOML files define team archetypes (roles, tasks, prompts)
  • One command: clawteam launch <template>
  • Variable substitution: {goal}, {team_name}, {agent_name}

v0.3.0 — Production Intelligence (New)

  • 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).
  • Cost Dashboard — real-time token/cost by agent, model, and task (clawteam board cost). No competitor has this.
  • Circuit Breaker — healthy → degraded → open tri-state with half-open probing
  • Retry with Backoffspawn_with_retry() for resilient agent spawning
  • Idempotency Keys — deduplication for create() and send()
  • Intent-Based Prompts — military C2 Auftragstaktik: agents get intent + end_state + constraints
  • Boids Emergence Rules — Reynolds 1986 flocking rules adapted for LLM agents
  • Metacognitive Self-Assessment — agents tag their own confidence levels
  • Per-Agent Model Resolution — 7-level priority chain, mix Claude/GPT/Qwen in one team
  • Runtime Live Injectionruntime inject/state/watch for messaging running agents

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.


OpenClaw Integration

This fork makes OpenClaw the default agent. Without ClawTeam, each OpenClaw agent works in isolation. ClawTeam transforms it into a multi-agent platform.

Capability OpenClaw Alone OpenClaw + ClawTeam
Task assignment Manual per-agent messaging Leader autonomously splits, assigns, monitors
Parallel development Shared working directory Isolated git worktrees per agent
Dependencies Manual polling --blocked-by with auto-unblock
Communication Only through AGI relay Direct point-to-point inbox + broadcast
Observability Read logs Kanban board + tiled tmux view

Once the skill is installed, talk to your OpenClaw bot in any channel:

What you say What happens
"Create a 5-agent team to build a web app" Creates team, tasks, and spawns 5 agents with the configured backend
"Launch a hedge-fund analysis team" clawteam launch hedge-fund with 7 agents
"Check the status of my agent team" clawteam board show with kanban output
  You (Telegram/Discord/TUI)
         │
         ▼
  ┌──────────────────┐
  │  OpenClaw Gateway │  ← activates clawteam skill
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐     clawteam spawn     ┌─────────────────┐
  │  Leader Agent    │ ─────────────────────► │  openclaw tui   │
  │  (openclaw)      │ ──┐                    │  (tmux window)  │
  │                  │   │                    │  git worktree   │
  │  Manages swarm   │   ├──────────────────► ├─────────────────┤
  │  via clawteam    │   │                    │  openclaw tui   │
  │  CLI             │   ├──────────────────► ├─────────────────┤
  └──────────────────┘   │                    │  openclaw tui   │
                         └──────────────────► └─────────────────┘
                                               All coordinate via
                                               ~/.clawteam/ (tasks, inboxes)

Hermes Agent Integration

ClawTeam ships first-class support for 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>").

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.

Capability Hermes Alone Hermes + ClawTeam
Parallelism Single session Spawn N workers in tmux windows
Coordination Manual Kanban + inboxes + task dependencies
Isolation Shared working dir Git worktrees per agent
Session hygiene Mixes with user sessions --source tool tag passed to Hermes (requires upstream fix — see SKILL.md Known upstream issues)

Using Hermes with ClawTeam:

All built-in templates (hedge-fund, research-paper, code-review, strategy-room) default to spawning OpenClaw workers. Hermes users pass --command hermes to override:

clawteam launch hedge-fund --team-name <name> --goal "..." --command hermes --force

Or spawn manually, passing hermes as the trailing positional argument:

clawteam spawn --team <team> --agent-name <name> --task "..." --no-workspace hermes

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:

tmux capture-pane -t clawteam-<team>:<window-index> -p -S -500

Installation: see Step 5b in the Install section.


Architecture

  Human: "Optimize this LLM"
         │
         ▼
  ┌──────────────┐     clawteam spawn     ┌──────────────┐
  │  Leader      │ ──────────────────────► │  Worker      │
  │  (any agent) │ ──────┐                │  git worktree │
  │              │       ├──────────────► │  tmux window  │
  │  spawn       │       │                ├──────────────┤
  │  task create │       ├──────────────► │  Worker      │
  │  inbox send  │       │                │  git worktree │
  │  board show  │       └──────────────► │  tmux window  │
  └──────────────┘                        └──────────────┘
                                                 │
                                                 ▼
                                      ┌─────────────────────┐
                                      │    ~/.clawteam/     │
                                      │ ├── teams/   (who) │
                                      │ ├── tasks/   (what)│
                                      │ ├── inboxes/ (talk)│
                                      │ └── workspaces/    │
                                      └─────────────────────┘

All state lives in ~/.clawteam/ as JSON files. No database, no server. Atomic writes with cross-platform file locking ensure crash safety.

Setting Env Var Default
Data directory CLAWTEAM_DATA_DIR ~/.clawteam
Transport CLAWTEAM_TRANSPORT file
Workspace mode CLAWTEAM_WORKSPACE auto
Spawn backend CLAWTEAM_DEFAULT_BACKEND tmux on Linux/macOS, subprocess on Windows

Command Reference

Core Commands
# Team lifecycle
clawteam team spawn-team <team> -d "description" -n <leader>
clawteam team discover                    # List all teams
clawteam team status <team>               # Show members
clawteam team cleanup <team> --force      # Delete team

# Spawn agents (note: `spawn` uses --team; `launch` uses --team-name)
clawteam spawn --team <team> --agent-name <name> --task "do this"
clawteam spawn codex --team <team> --agent-name <name> --task "do this"
clawteam spawn --team <team> --agent-name <name> --task "do this" hermes
clawteam spawn subprocess hermes --team <team> --agent-name <name> --task "do this"

# Task management
clawteam task create <team> "subject" -o <owner> --blocked-by <id1>,<id2>
clawteam task update <team> <id> --status completed   # auto-unblocks dependents
clawteam task list <team> --status blocked --owner worker1
clawteam task wait <team> --timeout 300

# Messaging
clawteam inbox send <team> <to> "message"
clawteam inbox broadcast <team> "message"
clawteam inbox receive <team>             # consume messages
clawteam inbox peek <team>                # read without consuming

# Monitoring
clawteam board show <team>                # terminal kanban
clawteam board live <team> --interval 3   # auto-refresh
clawteam board attach <team>              # tiled tmux view (Linux/macOS/WSL)
clawteam board serve --port 8080          # web UI
Workspace, Plan, Lifecycle, Config
# Workspace (git worktree management)
clawteam workspace list <team>
clawteam workspace checkpoint <team> <agent>    # auto-commit
clawteam workspace merge <team> <agent>         # merge back to main
clawteam workspace cleanup <team> <agent>       # remove worktree

# Plan approval
clawteam plan submit <team> <agent> "plan" --summary "TL;DR"
clawteam plan approve <team> <plan-id> <agent> --feedback "LGTM"
clawteam plan reject <team> <plan-id> <agent> --feedback "Revise X"

# Lifecycle
clawteam lifecycle request-shutdown <team> <agent> --reason "done"
clawteam lifecycle approve-shutdown <team> <request-id> <agent>
clawteam lifecycle idle <team>

# Templates
clawteam launch <template> --team <name> --goal "Build X"
clawteam template list

# Config
clawteam config show
clawteam config set transport p2p
clawteam config health

Per-Agent Model Assignment

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.

Per-agent model in templates:

[template]
name = "my-team"
command = ["openclaw"]
model = "sonnet-4.6"              # default for all agents
model_strategy = "auto"           # or: leaders→strong, workers→balanced

[template.leader]
name = "lead"
model = "opus"                    # override for leader

[[template.agents]]
name = "worker"
model_tier = "cheap"              # cost tiers: strong / balanced / cheap

CLI flags:

clawteam spawn --model opus                          # single agent
clawteam launch my-template --model gpt-5.4          # override all agents
clawteam launch my-template --model-strategy auto     # auto-assign by role

Roadmap

Version What Status
v0.2 OpenClaw default agent, workspace overlay, zombie detection, 11-language README Shipped
v0.3 Research-backed intelligence, cost dashboard, circuit breaker, per-agent models, runtime injection Shipped
v0.4 Windows full support, A2A Gateway integration In Progress
v0.5 Agent template marketplace — community-contributed TOML templates Planned
v0.6 Memory deep integration — per-team/per-task knowledge sharing Planned
v1.0 Production-grade — auth, permissions, audit logs Exploring

Contributing

We welcome contributions! See CONTRIBUTING.md for setup, code style, and PR guidelines.

Areas we'd love help with:

  • Agent integrations — support for more CLI agents
  • Team templates — TOML templates for new domains
  • Transport backends — Redis, NATS, etc.
  • Dashboard improvements — Web UI, Grafana
  • Documentation — tutorials and best practices

Acknowledgements

License

MIT — free to use, modify, and distribute.


ClawTeamAgent Swarm Intelligence.

About

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

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Packages

 
 
 

Contributors