<h1 align="center"><img src="assets/icon.png" alt="" width="64" style="vertical-align: middle;"> ClawTeam: Agent Swarm Intelligence</h1>
<p align="center">
<strong>The Evolution of AI Agents ๐: Solo ๐ค โ Swarm ๐ฆ๐ค๐ค๐ค<br>
ClawTeam: Let AI Agents Form Swarms, Think & Work Together, and Ship Faster</strong>
</p>
<p align="center">
<a href="#-quick-start"><img src="https://img.shields.io/badge/Quick_Start-3_min-blue?style=for-the-badge" alt="Quick Start"></a>
<a href="#-use-cases"><img src="https://img.shields.io/badge/Use_Cases-3_Demos-green?style=for-the-badge" alt="Use Cases"></a>
<a href="#-features"><img src="https://img.shields.io/badge/Features-12+-purple?style=for-the-badge" alt="Features"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"></a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/python-โฅ3.10-blue?logo=python&logoColor=white" alt="Python">
<img src="https://img.shields.io/badge/typer-CLI-green" alt="Typer">
<img src="https://img.shields.io/badge/agents-Claude_Code_%7C_Codex_%7C_Any_CLI-blueviolet" alt="Agents">
<img src="https://img.shields.io/badge/transport-File_%7C_ZeroMQ_P2P-orange" alt="Transport">
<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
</p>
**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
<table align="center" width="100%">
<tr>
<td width="25%" align="center" style="vertical-align: top; padding: 15px;">
<h3>๐ฌ AI Research Automation</h3>
<div align="center">
<img src="https://img.shields.io/badge/AutoResearch-FF6B6B?style=for-the-badge&logo=pytorch&logoColor=white" alt="AutoResearch" />
</div>
<img src="assets/scene-autoresearch.png" width="180">
<p align="center"><strong>โข Large-Scale Automated ML Experimentation</strong></p>
<p align="center"><strong>โข AI Model Training & Optimization</strong></p>
<p align="center"><strong>โข AI-Driven Hypothesis Generation & Validation</strong></p>
<p align="center"><strong>โข Self-Improving Model Architectures</strong></p>
</td>
<td width="25%" align="center" style="vertical-align: top; padding: 15px;">
<h3>๐๏ธ Agentic Engineering</h3>
<div align="center">
<img src="https://img.shields.io/badge/Full--Stack_Dev-4ECDC4?style=for-the-badge&logo=git&logoColor=white" alt="Engineering" />
</div>
<img src="assets/scene-engineering.png" width="180">
<p align="center"><strong>โข Autonomous Full-Stack Development</strong></p>
<p align="center"><strong>โข Self-Evolving Software</strong></p>
<p align="center"><strong>โข Collaborative Open Source Development</strong></p>
<p align="center"><strong>โข Real-Time System Integration</strong></p>
</td>
<td width="25%" align="center" style="vertical-align: top; padding: 15px;">
<h3>๐ฐ AI Hedge Fund</h3>
<div align="center">
<img src="https://img.shields.io/badge/Investment_Analysis-FFD93D?style=for-the-badge&logo=bitcoin&logoColor=black" alt="Hedge Fund" />
</div>
<img src="assets/scene-hedgefund.png" width="180">
<p align="center"><strong>โข Automated Market Research & Data Mining</strong></p>
<p align="center"><strong>โข Multi-Strategy Portfolio Optimization</strong></p>
<p align="center"><strong>โข Real-Time Risk Assessment</strong></p>
<p align="center"><strong>โข Algorithmic Trading Execution & Monitoring</strong></p>
</td>
<td width="25%" align="center" style="vertical-align: top; padding: 15px;">
<h3>๐ช Your Own Swarm</h3>
<div align="center">
<img src="https://img.shields.io/badge/TOML_Templates-C77DFF?style=for-the-badge&logo=toml&logoColor=white" alt="Templates" />
</div>
<img src="assets/scene-template.png" width="180">
<p align="center"><strong>โข Custom Scientific Research Teams</strong></p>
<p align="center"><strong>โข Personalized Investment Committees</strong></p>
<p align="center"><strong>โข Business Operations Teams</strong></p>
<p align="center"><strong>โข Content Production Studios</strong></p>
</td>
</tr>
</table>
---
<table align="center" width="100%">
<tr>
<td width="50%" align="center" style="vertical-align: top; padding: 10px;">
<strong>v0.1.0</strong>
https://github.com/user-attachments/assets/7e2f0ecd-8fe3-4970-90ac-5c9669ff060c
</td>
<td width="50%" align="center" style="vertical-align: top; padding: 10px;">
<strong>v0.2.0</strong>
https://github.com/user-attachments/assets/fd23be91-5cf4-457c-a77e-bac24b76e58f
</td>
</tr>
</table>
โ๏ธ 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.
<p align="center">
<img src="assets/teaser.png" alt="ClawTeam - AI agents orchestrating themselves" width="800">
</p>
---
## ๐ค 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.
<p align="center">
<img src="assets/comic-how-it-works.png" alt="How ClawTeam works - comic" width="700">
</p>
---
## ๐ฏ Swarm Intelligence in Action
<table>
<tr>
<td width="33%">
### ๐ฆ 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"
```
</td>
<td width="33%">
### ๐ค 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."
```
</td>
<td width="33%">
### ๐ 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
```
</td>
</tr>
</table>
| | 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.
<p align="center">
<img src="assets/autoresearch-progress.png" alt="AutoResearch Progress" width="720">
<br>
<em>๐ val_bpb: 1.044 โ 0.977 (6.4% improvement) | 2430+ experiments | ~30 GPU-hours</em>
</p>
**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 <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:
```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 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:
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 <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.
```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
# 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:
```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 <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:
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 <your-agent> --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, MiniMax, or Gemini via
Vertex, use `profile` + `preset` and then spawn with `--profile`.
---
## โจ Features
<table>
<tr>
<td width="50%">
### ๐ฆ 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
</td>
<td width="50%">
### ๐ฌ 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 <template>`
- Built-in: AI Hedge Fund (7 agents). Create your own.
- Variable substitution: `{goal}`, `{team_name}`, `{agent_name}`
</td>
</tr>
</table>
### ๐ง More
| Feature | Description |
|---------|-------------|
| ๐ **Plan Approval** | Agents submit plans for leader review before execution |
| ๐ **Lifecycle Protocol** | Graceful shutdown request/approve/reject, idle notifications |
| ๐ **JSON Output** | `--json` flag on all commands โ agents parse structured output |
| ๐ **Cross-Machine** | Shared filesystem (NFS/SSHFS) or P2P transport for distributed teams |
| ๐ฅ **Multi-User** | Namespace agents by user โ multiple humans can share a team |
| โ๏ธ **Configuration** | Persistent config: env var > config file > default priority |
| ๐ **Agent Skill** | Reusable skill entry for Claude Code and Codex workflows |
---
## ๐ค How Agents Use ClawTeam
When an agent is spawned via `clawteam spawn`, it receives an **auto-injected coordination prompt**:
```
## Coordination Protocol (auto-injected into every spawned agent)
- ๐ Check your tasks: clawteam task list <team> --owner <your-name>
- โถ๏ธ Start a task: clawteam task update <team> <id> --status in_progress
- โ
Finish a task: clawteam task update <team> <id> --status completed
- ๐ฌ Message leader: clawteam inbox send <team> leader "status update..."
- ๐ฌ Message teammate: clawteam inbox send <team> <name> "info..."
- ๐จ Check inbox: clawteam inbox receive <team>
- ๐ด Report idle: clawteam lifecycle idle <team>
```
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
<details open>
<summary><h3>๐ง Core Commands</h3></summary>
```bash
# ๐๏ธ 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
```
</details>
<details>
<summary><h3>๐ณ Workspace, ๐ Plan, ๐ Lifecycle, โ๏ธ Config</h3></summary>
```bash
# ๐ณ 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_*`.
</details>
---
## ๐๏ธ Architecture
```
Human: "Optimize this LLM"
โ
โผ
โโโโโโโโโโโโโโโโ clawteam spawn โโโโโโโโโโโโโโโโ
โ ๐ฆ Leader โ โโโโโโโโโโโโโโโโโโโโโโโบ โ ๐ค Worker โ
โ (Claude Code)โ โโโโโโโ โ (Claude Code)โ
โ โ โ โ git worktree โ
โ Uses: โ โ โ tmux window โ
โ โข spawn โ โ clawteam spawn โโโโโโโโโโโโโโโโ
โ โข task createโ โ
โ โข inbox send โ โผ โโโโโโโโโโโโโโโโ
โ โข board show โ โโโโโโโโโโโโโโโโโโโโโโโบ โ ๐ค Worker โ
โ โข task wait โ โ โ (Codex) โ
โโโโโโโโโโโโโโโโ โ โ git worktree โ
โ โ tmux window โ
โ clawteam spawn โโโโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโ
โ ๐ค Worker โ Each worker uses:
โ (any CLI) โ โข task list (check work)
โ git worktree โ โข task update (report done)
โ tmux window โ โข inbox send (message leader)
โโโโโโโโโโโโโโโโ โข inbox receive (get instructions)
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโ
โ ~/.clawteam/ โ
โ โโโ teams/ (who) โ
โ โโโ tasks/ (what)โ
โ โโโ inboxes/ (talk)โ
โ โโโ workspaces/ โ
โ (isolated code)โ
โโโโโโโโโโโโโโโโโโโโโโโ
```
All state lives in `~/.clawteam/` as JSON files. No database, no server, no cloud. Atomic `tmp + rename` writes ensure crash safety.
| Spawn Default | Value | Override |
|---------------|-------|----------|
| Backend | `tmux` | `clawteam spawn subprocess ...` |
| Command | `claude` | `clawteam spawn tmux codex ...` |
| Workspace | `auto` (git worktree) | `--no-workspace` |
| Permissions | skip | `--no-skip-permissions` |
| 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 |
### Milestones
| Milestone | Status | Notes |
|---|---|---|
| v0.1.x | โ
Shipped | Core CLI, team/task/inbox flows, board, templates, packaging. |
| v0.2.0 | โ
Released | Stabilization, docs refresh, spawn/workspace fixes, and release packaging. |
| v0.3 | ๐ Roadmap baseline | File + P2P transport, Web UI, multi-user workflow, team templates. |
For the longer-term plan, see [ROADMAP.md](ROADMAP.md).
---
## ๐ค Contributing
We welcome contributions! ClawTeam is designed to be extensible:
- ๐ค **New agent integrations** โ Add support for more AI coding agents
- ๐ช **Team templates** โ Create TOML templates for new domains (DevOps, data science, etc.)
- ๐ **Transport backends** โ Redis, NATS, or other message transports
- ๐ **Dashboard improvements** โ Enhanced Web UI, Grafana integration
- ๐ **Documentation** โ Tutorials, best practices, agent prompt engineering guides
---
## ๐ Acknowledgements
- [@karpathy/autoresearch](https://github.com/karpathy/autoresearch) โ the autonomous ML research framework used in our 8-agent swarm demo
- [Claude Code](https://claude.ai/claude-code) and [Codex](https://openai.com/codex) โ AI coding agents that work as ClawTeam team members
- [ai-hedge-fund](https://github.com/virattt/ai-hedge-fund) โ inspiration for the multi-analyst hedge fund template
- [CLI-Anything](https://github.com/HKUDS/CLI-Anything) โ sister project making all software agent-native
---
## โญ Star History
If you find ClawTeam helpful, please consider giving us a star! โญ
<div align="center">
<a href="https://star-history.com/#HKUDS/ClawTeam&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/ClawTeam&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/ClawTeam&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/ClawTeam&type=Date" />
</picture>
</a>
</div>
## ๐ License
MIT License โ free to use, modify, and distribute.
---
<div align="center">
**ClawTeam** โ *Agent Swarm Intelligence.* ๐ฆ
<sub>8 agents ร 8 H100s ร 2430 experiments ร one CLI ร one swarm</sub>
<br>
<img src="assets/icon.png" alt="ClawTeam" width="80">
</div>
<p align="center">
<em>Thanks for visiting โจ ClawTeam!</em><br><br>
<img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.ClawTeam&style=for-the-badge&color=00d4ff" alt="Views">
</p>