ClawTeam: Agents That Spawn and Manage Other Agents

One CLI command turns a single goal into an autonomous swarm of specialized LLMs that communicate, delegate, isolate their workspaces with git worktrees, and deliver results with almost no human oversight.

ClawTeam (HKUDS/ClawTeam) · Python · 873 stars · 18 min read

A single human hand holds one large CLI terminal window. From its edges, dozens of smaller mechanical robot arms branch outward like a tree or swarm, each grasping its own miniature terminal or tool. In the background, visible git worktree branches provide clean structural isolation between the arms. Black ink crosshatching on pure white background. — A single command launches an entire swarm. The branching structure visualizes how one leader terminal gives rise to dozens of specialized agents, each in its own isolated workspace.

Key Takeaways

ClawTeam inverts multi-agent orchestration by letting a single leader LLM autonomously spawn, delegate to, and manage an entire swarm of specialist agents through one CLI tool.
Agents coordinate using Unix primitives including git worktrees for workspace isolation, tmux for process management, and filesystem mailboxes for communication.
A leader agent given a high-level goal can autonomously run thousands of experiments across parallel agents and merge results back through git without human intervention.
ClawTeam requires no databases, containers, or heavy infrastructure, keeping all state in JSON files and making the entire system observable and hackable.

Agents That Run the OS

Most multi-agent frameworks require developers to write the orchestration code. ClawTeam does the opposite.

A single leader LLM receives a high-level goal and access to one CLI tool: clawteam. Using injected prompts that describe the entire coordination protocol, the leader autonomously spawns, delegates to, coordinates, and manages a swarm of specialist agents.

This inversion turns prompt engineering into systems design. The agents themselves become the operating system.

Close-up of two hands connected by a taut wire. The left hand is clearly human and labeled 'goal'. The right is a detailed mechanical LLM hand pulling levers labeled spawn, inbox, task, and board. The mechanical hand dominates the frame. Black ink crosshatching on pure white background. — The control inversion at the heart of ClawTeam. The leader agent uses the clawteam CLI to directly manage other agents rather than being managed by external code.

"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 README, HKU Data Intelligence Lab

From One Command to a Living Swarm

The user experience is deceptively simple. You launch a team with a TOML template or a single command, provide a goal, and then mostly watch.

The leader agent plans, spawns specialists (researcher, architect, tester, analyst), assigns tasks with dependencies, and uses inboxes for communication. Results flow back through git merges. A real-time board — either a tiled tmux view or web dashboard — makes the entire swarm observable.

In one documented run, a leader given the goal of optimizing an LLM training setup spawned eight agents, one per H100 GPU. They ran over 2,430 experiments autonomously, improving validation bits-per-byte from 1.044 to 0.977.

The Unix Philosophy for Agents

ClawTeam avoids heavy infrastructure by design. There is no database, no Redis, and no Docker by default. State lives in JSON files under ~/.clawteam/.

Isolation comes from git worktrees: each agent gets its own clean branch of the repository. Process management uses tmux sessions. Communication happens through filesystem mailboxes or optional ZeroMQ. This makes the system remarkably observable and hackable.

A clean mechanical machine on a simple wooden Unix workbench. Interlocking gears labeled tmux, branching file folders with isolation barriers labeled git worktrees, and pigeonhole slots with flying messages labeled mailbox all operate together smoothly. Black ink crosshatching on pure white background. — The minimalist primitives that replace traditional orchestration layers. tmux for sessions, git worktrees for isolation, and mailboxes for IPC.

# Example hedge-fund.toml template
team_name = "fund-analysis"
goal = "Analyze AAPL, MSFT, NVDA for Q2 2026"

[agents.portfolio-manager]
role = "leader"
responsibility = "Make final investment decisions"

[agents.value-analyst]
role = "specialist"
focus = "value investing metrics"

[agents.risk-manager]
role = "specialist"
focus = "portfolio risk assessment"

How the Coordination Actually Works

The core lives in clawteam/team/ with manager.py, mailbox.py, tasks.py, and plan.py. The spawn layer in clawteam/spawn/ supports tmux and subprocess backends.

When an agent runs clawteam spawn, the system creates a new git worktree, starts a tmux session, injects a rich prompt describing all available commands and team state, and registers the agent identity. Tasks use dependency graphs with locking to prevent race conditions.

Watchers and waiters provide synchronization primitives. Everything remains observable because the underlying tools (tmux, git, files) are visible to both humans and agents.

Real Teams in Action

Pre-built TOML templates make launching sophisticated teams trivial. The hedge-fund template spawns a portfolio manager plus multiple specialized analysts. A full-stack engineering template coordinates architect, backend, frontend, and tester agents with automatic merging.

The autonomous ML research example remains the most compelling demonstration. Inspired by Andrej Karpathy's autoresearch, the swarm ran thousands of experiments in parallel, cross-pollinated findings, and achieved measurable gains with zero human intervention after the initial goal.

Split composition. Left side shows chaotic pile of isolated agent terminals with tangled wires and a frustrated human figure in the center trying to coordinate. Right side shows clean organized branching structure with one leader terminal at the root and smooth information flow between orderly agent nodes. Black ink crosshatching on pure white background. — Traditional coordination versus ClawTeam's agent-driven approach. The right side shows the power of letting agents manage other agents.

ClawTeam vs. the Rest

Aspect	CrewAI / MetaGPT	OpenAI Swarm	ClawTeam
Orchestration model	Developer-written code or fixed graphs	Lightweight handoff scripts	Agents drive coordination via CLI
Infrastructure	Often requires servers or heavy setup	Minimal but limited	Filesystem, tmux, git worktrees only
Agent compatibility	Framework-specific agents	Custom agents	Any CLI-based agent
Isolation	Usually containers or shared state	Limited	Git worktrees per agent
Observability	Framework dashboards	Basic logging	tmux tiles + live kanban board
Best for	Structured, repeatable workflows	Simple handoffs	Dynamic research and engineering

Why This Matters Now

ClawTeam is part of a broader shift toward agent-native operating systems. By treating LLM agents as first-class processes with proper isolation, communication primitives, and observability, it blurs the line between prompt engineering and traditional systems architecture.

The project comes from the Data Intelligence Lab at the University of Hong Kong, led by Assistant Professor Chao Huang with significant contributions from Ph.D. student Jiabin Tang (tjb-tech). It builds on the lab's related work in the OpenClaw and nanobot ecosystem.

"Agents spawn agents. The leader agent calls clawteam spawn to create workers. Each worker gets its own git worktree, tmux window, and identity automatically."

— Jiabin Tang (tjb-tech), primary contributor

The minimalism is the point. When the entire coordination layer consists of tools that are already visible and debuggable, both humans and agents can understand and improve the system. That may prove more valuable than any amount of additional abstraction.