--- title: WitNote emoji: 🦞 colorFrom: blue colorTo: green sdk: docker app_port: 7860 ---

ClawTeam: Agent Swarm Intelligence

The Evolution of AI Agents 🚀: Solo 🤖 → Swarm 🦞🤖🤖🤖
ClawTeam: Let AI Agents Form Swarms, Think & Work Together, and Ship Faster

**One Command Line: Full Automation.** — agents spawn swarms, delegate tasks, and deliver results. Human provides the goal. The Agent Team orchestrates everything else. Full compatibility with [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/codex), [OpenClaw](https://github.com/openclaw/openclaw), [nanobot](https://github.com/HKUDS/nanobot), [Cursor](https://cursor.com), and any CLI agent. [**中文文档**](README_CN.md) | [**한국어**](README_KR.md) --- ## 📰 News **2026-03-18** ClawTeam project launched publicly. **2026-03-23** ClawTeam `v0.2.0` is released today. **2026-03** The current baseline includes config management, multi-user workflows, Web UI, P2P transport, and team templates. --- ## ✨ ClawTeam's Key Features

🔬 AI Research Automation

• Large-Scale Automated ML Experimentation

• AI Model Training & Optimization

• AI-Driven Hypothesis Generation & Validation

• Self-Improving Model Architectures

🏗️ Agentic Engineering

• Autonomous Full-Stack Development

• Self-Evolving Software

• Collaborative Open Source Development

• Real-Time System Integration

💰 AI Hedge Fund

• Automated Market Research & Data Mining

• Multi-Strategy Portfolio Optimization

• Real-Time Risk Assessment

• Algorithmic Trading Execution & Monitoring

🎪 Your Own Swarm

• Custom Scientific Research Teams

• Personalized Investment Committees

• Business Operations Teams

• Content Production Studios

---

v0.1.0 https://github.com/user-attachments/assets/7e2f0ecd-8fe3-4970-90ac-5c9669ff060c

v0.2.0 https://github.com/user-attachments/assets/fd23be91-5cf4-457c-a77e-bac24b76e58f

☝️ 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.

ClawTeam - AI agents orchestrating themselves

--- ## 🤔 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 • **📋 Designs intelligent task allocation** — with smart dependency management • **💬 Facilitates real-time coordination** — seamless inter-agent communication • **📊 Monitors team performance** — tracks progress and identifies bottlenecks • **🔄 Adapts strategies dynamically** — reallocates resources and redirects efforts #### ✨ The Result? You set the vision. The swarm executes with collective intelligence.

How ClawTeam works - comic

--- ## 🎯 Swarm Intelligence in Action

### 🦞 Agents Spawn Agents The leader agent calls `clawteam spawn` to create workers. Each worker gets its own **git worktree**, **tmux window**, and **identity** — automatically. ```bash # The leader agent runs: clawteam spawn --team my-team \ --agent-name worker1 \ --task "Implement auth module" ```

### 🤖 Agents Talk to Agents Workers check their inbox, update task status, and report results — all through CLI commands that are **auto-injected** into their prompt. ```bash # A worker agent checks tasks: clawteam task list my-team --owner me # Then reports back: clawteam inbox send my-team leader \ "Auth done. All tests passing." ```

### 👀 You Just Watch Monitor the swarm from a tiled tmux view or a Web UI. The leader handles coordination — you intervene only when you want to. ```bash # Watch all agents simultaneously clawteam board attach my-team # Or open the web dashboard clawteam board serve --port 8080 ```

| | ClawTeam | Other multi-agent frameworks | |---|---------|----------------------------| | 🎯 **Who uses it** | **The AI agents themselves** | Humans writing orchestration code | | ⚡ **Setup** | `pip install` + one prompt to the leader | Docker, cloud APIs, YAML configs | | 🏗️ **Infrastructure** | Just a filesystem and tmux | Redis, message queues, databases | | 🤖 **Agent support** | Any CLI agent (Claude Code, Codex, OpenClaw, custom) | Framework-specific only | | 🌳 **Isolation** | Git worktrees (real branches, real diffs) | Containers or virtual envs | | 🧠 **Intelligence** | Swarm self-organizes via CLI commands | Hard-coded orchestration logic | --- ## 🎬 Use Cases ### 🔬 1. Autonomous ML Research — 8 Agents × 8 H100 GPUs Based on [@karpathy's autoresearch](https://github.com/karpathy/autoresearch). #### 💫 One Command. Full Automation. #### Human input: "Optimize this LLM training setup using 8 GPUs" The Agent Team handles everything else: - Spawns 8 specialized research agents across H100s - Designs 2000+ autonomous experiments - Achieves breakthrough improvements (val_bpb: 1.044→0.977) - Zero human intervention required #### 🎯 Pure Research at Scale Transform months of manual hyperparameter tuning into hours of intelligent automation.

AutoResearch Progress
🏆 val_bpb: 1.044 → 0.977 (6.4% improvement) | 2430+ experiments | ~30 GPU-hours

**What agent team did autonomously:** ``` Human prompt: "Use 8 GPUs to optimize train.py. Read program.md for instructions." 🦞 Leader agent's actions: ├── 📖 Read program.md, understand the experiment protocol ├── 🏗️ clawteam team spawn-team autoresearch ├── 🚀 Assigned each GPU a research direction: │ ├── GPU 0: clawteam spawn --task "Explore model depth (DEPTH 10-16)" │ ├── GPU 1: clawteam spawn --task "Explore model width (ASPECT_RATIO 80-128)" │ ├── GPU 2: clawteam spawn --task "Tune learning rates and optimizer" │ ├── GPU 3: clawteam spawn --task "Explore batch size and accumulation" │ ├── GPU 4-7: clawteam spawn tmux codex --task "..." (Codex agents) │ └── 🌳 Each agent: own git worktree, own branch, isolated experiments ├── 🔄 Every 30 minutes, checked results: │ ├── clawteam board show autoresearch │ ├── Read each agent's results.tsv │ ├── 🏆 Identified best findings (depth=12, batch=2^17, norm-before-RoPE) │ └── 📡 Cross-pollinated: told new agents to start from the best config ├── 🔧 When agents finished, reassigned GPUs: │ ├── Killed idle agents, cleaned worktrees │ ├── Created new worktrees from the best commit │ └── Spawned fresh agents with combined optimization directions └── ✅ After 2430+ experiments: val_bpb 1.044 → 0.977 ``` Full results: [novix-science/autoresearch](https://github.com/novix-science/autoresearch) --- ### 🏗️ 2. Agentic Software Engineering 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 --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: ```bash # 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 ```bash pip install clawteam # Or from source git clone https://github.com/HKUDS/ClawTeam.git cd ClawTeam pip install -e . # Optional: P2P transport (ZeroMQ) pip install -e ".[p2p]" ``` Requires **Python 3.10+**, **tmux**, and a CLI coding agent (e.g. `claude`, `codex`). Python dependencies: `typer`, `pydantic`, `rich`. 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: 1. Make sure `tmux` and your agent CLI run standalone on this machine. 2. Pick one path below: let an agent drive, or drive it manually. 3. Use the supported-agent table to choose the right `spawn` command. 4. If you're integrating a new agent, check the adapter notes before debugging. ### ✅ Before You Start Run these checks first: ```bash 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 ```bash # 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 --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. ```bash # 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 # 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 ``` 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: ```bash # 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 ` 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: 1. The command must exist on `PATH` and launch successfully outside ClawTeam. 2. The agent must be able to run inside a specific working directory or git worktree. 3. The agent must accept an initial task, either by command-line argument or interactive input. 4. 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: ```bash clawteam spawn subprocess --team my-team --agent-name test --task "Say OK" ``` If that works, switch to `tmux` for interactive monitoring. ### 🤖 Supported Agents ClawTeam works with **any CLI agent** that can execute shell commands: All examples below assume the corresponding CLI already runs standalone on your machine. | Agent | Spawn Command | Status | |-------|--------------|--------| | [Claude Code](https://claude.ai/claude-code) | `clawteam spawn tmux claude --team ...` | ✅ Full support | | [Codex](https://openai.com/codex) | `clawteam spawn tmux codex --team ...` | ✅ Full support | | [OpenClaw](https://github.com/openclaw/openclaw) | `clawteam spawn tmux openclaw --team ...` | ✅ Full support | | [nanobot](https://github.com/HKUDS/nanobot) | `clawteam spawn tmux nanobot --team ...` | ✅ Full support | | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | `clawteam spawn tmux kimi --team ...` | ✅ Full support | | [Cursor](https://cursor.com) | `clawteam spawn subprocess cursor --team ...` | 🔮 Experimental | | Custom scripts | `clawteam spawn subprocess python --team ...` | ✅ Full support | For provider-aware setups such as Claude Code via Moonshot Kimi or Gemini via Vertex, use `profile` + `preset` and then spawn with `--profile`. --- ## ✨ Features

### 🦞 Agent Self-Organization - Leader agents spawn and manage worker agents - **Auto-injected coordination prompt** — zero manual setup - Workers self-report status, results, and idle state - Works with any CLI agent: Claude Code, Codex, OpenClaw, custom ### 🌳 Workspace Isolation - Each agent gets its own **git worktree** (separate branch) - No merge conflicts between parallel agents - Checkpoint, merge, and cleanup commands - Branch naming: `clawteam/{team}/{agent}` ### 📋 Task Tracking with Dependencies - Shared kanban: `pending` → `in_progress` → `completed` / `blocked` - `--blocked-by` dependency chains — **auto-unblock on completion** - `task wait` blocks until all tasks complete - Filter by status, owner; JSON output for scripting

### 💬 Inter-Agent Messaging - Point-to-point **inboxes** (send, receive, peek) - **Broadcast** to all team members - File-based (default) or ZeroMQ P2P transport with offline fallback - Agents discover messages via `inbox receive` ### 📊 Monitoring & Dashboards - `board show` — terminal kanban board - `board live` — auto-refreshing dashboard - `board attach` — **tiled tmux view** of all agents working - `board serve` — **Web UI** with real-time updates ### 🎪 Team Templates - **TOML files** define team archetypes (roles, tasks, prompts) - One command launches a complete team: `clawteam launch

ClawTeam: Agent Swarm Intelligence

🔬 AI Research Automation

🏗️ Agentic Engineering

💰 AI Hedge Fund

🎪 Your Own Swarm

🔧 Core Commands

🌳 Workspace, 📝 Plan, 🔄 Lifecycle, ⚙️ Config