☝️ Intelligent leader agent orchestrates 8 specialized sub-agents across 8 H100 GPUs, autonomously designing experiments and dynamically reallocating resources based on real-time performance.
🧠 The system synthesizes breakthroughs across teams and evolves strategies independently — achieving full research automation without human intervention.
🤔 Why ClawTeam?
Current AI agents are powerful — but they work in isolation. When facing complex tasks, you're stuck manually coordinating multiple agents, juggling context, and stitching together fragmented results.
What if agents could think and work as a team?
ClawTeam unlocks Agent Swarm Intelligence — where AI agents self-organize into collaborative teams, intelligently divide complex work, share insights in real-time, and converge on breakthrough solutions.
• 🚀 Spawns specialized sub-agents — each with dedicated environments and focus areas
You tell Claude Code: "Build me a full-stack todo app." Claude realizes this is a multi-module task and self-organizes a team:
Human prompt: "Build a full-stack todo app with auth, database, and React frontend."
🦞 Leader agent's actions:
├── 🏗️ clawteam team spawn-team webapp -d "Full-stack todo app"
├── 📋 Created tasks with dependency chains:
│ ├── T1: "Design REST API schema" → architect
│ ├── T2: "Implement JWT auth" --blocked-by T1 → backend1
│ ├── T3: "Build database layer" --blocked-by T1 → backend2
│ ├── T4: "Build React frontend" → frontend
│ └── T5: "Integration tests" --blocked-by T2,T3,T4 → tester
├── 🚀 Spawned 5 sub-agents (each in its own git worktree):
│ ├── clawteam spawn --agent-name architect --task "Design the API schema"
│ ├── clawteam spawn --agent-name backend1 --task "Implement JWT auth"
│ ├── clawteam spawn --agent-name backend2 --task "Build PostgreSQL models"
│ ├── clawteam spawn --agent-name frontend --task "Build React UI"
│ └── clawteam spawn --agent-name tester --task "Write pytest tests"
├── 🔗 Dependency auto-resolution:
│ ├── architect completes → backend1 and backend2 auto-unblock
│ ├── All backends complete → tester auto-unblocks
│ └── Each agent calls: clawteam task update <id> --status completed
├── 💬 Sub-agents coordinate via inbox:
│ ├── architect → backend1: "Here's the OpenAPI spec: ..."
│ ├── backend1 → tester: "Auth endpoints ready at /api/auth/*"
│ └── tester → leader: "All 47 tests passing ✅"
└── 🌳 Leader merges all worktrees into main branch
💰 3. AI Hedge Fund — One-Command Team Launch
A pre-built TOML template spawns a complete 7-agent investment analysis team:
# One command launches everything:
clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"
🦞 What happens automatically:
├── 📊 Portfolio Manager (leader) spawns and receives the goal
├── 🤖 5 Analyst agents spawn, each with a different strategy:
│ ├── 🎩 Buffett Analyst → value investing (moat, ROE, DCF)
│ ├── 🚀 Growth Analyst → disruption (TAM, network effects)
│ ├── 📈 Technical Analyst → indicators (EMA, RSI, Bollinger)
│ ├── 📋 Fundamentals → financial ratios (P/E, D/E, FCF)
│ └── 📰 Sentiment Analyst → news + insider trading signals
├── 🛡️ Risk Manager spawns, waits for all analyst signals:
│ ├── clawteam inbox receive fund1 (collects all 5 signals)
│ ├── Consolidates + computes position limits
│ └── clawteam inbox send fund1 portfolio-manager "RISK REPORT: ..."
└── 💼 Portfolio Manager makes final buy/sell/hold decisions
Templates are TOML files — create your own team archetypes for any domain.
📦 Install
pip install clawteam
# Or install into an isolated user venv at ~/.clawteam/.venv
scripts/install_clawteam.sh
# Or from source
git clone https://github.com/HKUDS/ClawTeam.git
cd ClawTeam
pip install -e .
# Or install this checkout into ~/.clawteam/.venv
scripts/clawteam_local_install
# Optional: P2P transport (ZeroMQ)
pip install -e ".[p2p]"
Requires Python 3.10+, tmux, and a CLI coding agent (e.g. claude, codex). The install scripts create/reuse ~/.clawteam/.venv, link ~/.local/bin/clawteam, and install/update the bundled clawteam skill for detected clients.
Skill install targets are detected from existing config directories, including Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode, Nanobot, Cursor, OpenHarness (~/.openharness/skills), and Ohmo (~/.ohmo/skills).
All spawn examples assume the agent CLI you name is already installed and available on PATH.
🚀 Quick Start
If you're new to ClawTeam, follow this order:
Make sure tmux and your agent CLI run standalone on this machine.
Pick one path below: let an agent drive, or drive it manually.
Use the supported-agent table to choose the right spawn command.
If you're integrating a new agent, check the adapter notes before debugging.
✅ Before You Start
Run these checks first:
tmux -V
clawteam --help
# Replace claude with the agent you actually want to use:
claude --version
codex --version
nanobot --help
If the agent CLI does not run correctly by itself, clawteam spawn will not fix it.
⚡ Option 1: Let the Agent Drive (Recommended)
ClawTeam ships with a reusable skill in skills/clawteam/.
Claude Code
Install the skill into ~/.claude/skills/clawteam, then prompt:
"Build a web app. Use clawteam to split the work across multiple agents."
Codex
Install the same skill into $CODEX_HOME/skills/clawteam (typically ~/.codex/skills/clawteam), then prompt:
Use $clawteam to split this task across multiple agents and coordinate the team to completion.
The agent will automatically create a team, spawn workers, assign tasks, and coordinate — using clawteam CLI commands under the hood.
🔧 Option 2: Drive It Manually
# 1. Create a team (you become the leader)
clawteam team spawn-team my-team -d "Build the auth module" -n leader
# 2. Spawn worker agents — each gets a git worktree, tmux window, and identity
clawteam spawn --team my-team --agent-name alice --task "Implement the OAuth2 flow"
clawteam spawn --team my-team --agent-name bob --task "Write unit tests for auth"
# 3. Workers auto-receive a coordination prompt that teaches them to:
# ✅ Check tasks: clawteam task list my-team --owner alice
# ✅ Update status: clawteam task update my-team <id> --status completed
# ✅ Message leader: clawteam inbox send my-team leader "Done!"
# ✅ Report idle: clawteam lifecycle idle my-team
# 4. Watch them work side-by-side
clawteam board attach my-team
🧩 Profiles and Presets
When you want to use a non-default provider, model, or API gateway, configure a
profile first instead of manually exporting provider env vars each time.
# See built-in provider templates
clawteam preset list
clawteam preset show moonshot-cn
# Generate a reusable runtime profile from a preset
clawteam preset generate-profile moonshot-cn claude --name claude-kimi
# MiniMax (M2.7) — global or China endpoint
clawteam preset generate-profile minimax-global claude --name claude-minimax
clawteam preset generate-profile minimax-cn claude --name claude-minimax-cn
# Or use the interactive TUI
clawteam profile wizard
# Claude Code on a fresh machine/home may need this once
clawteam profile doctor claude
# Smoke-test the profile before spawning workers
MOONSHOT_API_KEY=... clawteam profile test claude-kimi
MINIMAX_API_KEY=... clawteam profile test claude-minimax
Rules of thumb:
profile is the final runtime object used by spawn / launch
preset is a reusable provider template that generates one or more profiles
wizard is the easiest path for first-time setup
doctor is mainly for Claude Code first-run onboarding state
🧭 Which Spawn Command Should I Use?
Use clawteam spawn [backend] [command] ... with the command that already works on
your machine:
# Claude Code
clawteam spawn tmux claude --team my-team --agent-name alice --task "Implement OAuth2"
# Codex
clawteam spawn tmux codex --team my-team --agent-name bob --task "Write frontend tests"
# nanobot
clawteam spawn tmux nanobot --team my-team --agent-name carol --task "Build the API"
# A configured profile (recommended for non-default providers/models)
clawteam spawn tmux --profile claude-kimi --team my-team --agent-name dave --task "Refactor the auth flow"
Notes:
tmux is the default backend and is the best choice when you want to watch interactive agent UIs.
subprocess is better for one-shot tools or non-interactive scripts.
nanobot is normalized internally to nanobot agent, so the command above is the correct ClawTeam entrypoint.
Claude Code and Codex trust prompts in fresh worktrees are auto-confirmed by the tmux backend.
For non-default providers/models, prefer --profile <name> over manually exporting env vars inline.
🔌 Adding a Different Agent
ClawTeam can work with agents beyond Claude Code, Codex, and nanobot, but the CLI
must satisfy a small compatibility contract:
The command must exist on PATH and launch successfully outside ClawTeam.
The agent must be able to run inside a specific working directory or git worktree.
The agent must accept an initial task, either by command-line argument or interactive input.
The process must stay alive in tmux if it is meant to be interactive.
If you're unsure, test the agent standalone first, then wrap it with:
This means any CLI agent can participate in a ClawTeam team — it just needs to run shell commands. No custom SDK, no API integration, no framework lock-in.
📖 Command Reference
# 🏗️ 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
clawteam spawn --team <team> --agent-name <name> --task "do this"
clawteam spawn tmux codex --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
clawteam board serve --port 8080 # web UI
# 🌳 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
| Setting | Env Var | Default | Description |
|---------|---------|---------|-------------|
| data_dir | CLAWTEAM_DATA_DIR | ~/.clawteam | Data directory |
| transport | CLAWTEAM_TRANSPORT | file | file or p2p |
| workspace | CLAWTEAM_WORKSPACE | auto | auto / always / never |
| default_backend | CLAWTEAM_DEFAULT_BACKEND | tmux | tmux or subprocess |
| skip_permissions | CLAWTEAM_SKIP_PERMISSIONS | true | Auto-approve agent tools |
Legacy aliases:
OH_* env vars are still accepted for compatibility, but new docs and examples use CLAWTEAM_*.
| Transport | How it works | When to use |
|-----------|-------------|-------------|
| file (default) | JSON files in inbox dirs | Single machine, shared FS |
| p2p | ZeroMQ PUSH/PULL + file fallback | Low-latency, auto-fallback |
🗺️ Roadmap
| Phase | Version | What | Status |
|-------|---------|------|--------|
| Current | v0.3 | File + P2P (ZeroMQ) transport, Web UI, multi-user, team templates | ✅ Shipped |
| Phase 1 | v0.4 | Redis Transport — cross-machine messaging | 🔜 Planned |
| Phase 2 | v0.5 | Shared State Layer — team config and tasks across machines | 🔜 Planned |
| Phase 3 | v0.6 | Agent Marketplace — discover and reuse community agent templates | 💡 Exploring |
| Phase 4 | v0.7 | Adaptive Scheduling — dynamically reassign tasks based on agent performance | 💡 Exploring |
| Phase 5 | v1.0 | Production-grade — auth, permissions, audit logs | 💡 Exploring |