ClawTeam
"ClawTeam: Agent Swarm Intelligence" (One Command → Full Automation)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/hkuds--clawteam)HTML
<a href="/listings/hkuds--clawteam"><img src="/api/listings/hkuds--clawteam/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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`.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 856 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <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>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.