ClawTeam Documentation

ClawTeam is a CLI tool designed to enable AI Agents to autonomously form teams, assign tasks, and collaborate to achieve complex goals. Instead of humans manually splitting tasks and managing context, a 'Leader Agent' can orchestrate a swarm of 'Worker Agents'.

Key capabilities include:

• Autonomous Team Formation: A Leader Agent can spawn sub-agents, each with its own Git Worktree and tmux session.
• Task Orchestration: Supports dependency chains and automated task unblocking.
• Agent Communication: Agents communicate via CLI commands (inbox/task management).
• Broad Agent Support: Works with any CLI-based agent, including Claude Code, Codex, OpenClaw, nanobot, and Cursor.
• Low Infrastructure Overhead: Uses the local file system and tmux rather than requiring complex message queues or databases.

ClawTeam is an Agent Swarm Intelligence framework providing:

• Agent Self-Organization: Leader Agents manage Worker Agents with automatic collaboration prompt injection.
• Workspace Isolation: Each agent operates in an independent Git Worktree (separate branch) to prevent conflicts.
• Agent Communication: Supports point-to-point inboxes (send, receive, preview), broadcasts to all members, and file transfers (default) or ZeroMQ P2P transport.
• Task Tracking: Dependency-aware task management with a shared Kanban board.

ClawTeam operates as a decentralized swarm intelligence system. It does not require a database, server, or cloud provider. All state is stored locally as JSON files under ~/.clawteam/ in the following structure:

• teams/: Team definitions.
• tasks/: Task data.
• inboxes/: Communication/messages.
• workspaces/: Isolated code environments (git worktrees).

Transport Modes

• file (Default): Uses JSON files in the inbox directory. Best for single machines or shared filesystems.
• p2p: Uses ZeroMQ PUSH/PULL with a file fallback. Best for low-latency communication.

Spawn Defaults

• Backend: tmux (Override with clawteam spawn subprocess ...)
• Command: claude (Override with clawteam spawn tmux codex ...)
• Workspace: auto (git worktree) (Override with --no-workspace)
• Permissions: skip (Override with --no-skip-permissions)

ClawTeam uses two orthogonal (non-interfering) systems for communication and state management:

You can delegate task orchestration to AI agents by installing ClawTeam skills. This allows agents like Claude Code or Codex to internally use the clawteam CLI to spawn teams, divide tasks, and coordinate workers.

• Claude Code: Install the skill to ~/.claude/skills/clawteam.
• Codex: Install the skill to $CODEX_HOME/skills/clawteam (typically ~/.codex/skills/clawteam).

The transport mechanism is determined by the transport field in your configuration and the method used to bind the agent.

• Transport Selection: The _default_transport() function is driven by the transport field in config.py.
• P2P Mode: Using bind_agent (from identity.py) enables P2P mode.
• Dependencies:
  • Required: typer, pydantic, rich
  • Optional (for P2P): pyzmq (must be installed to use P2PTransport)

Instead of manually exporting environment variables for every task, use Profiles and Presets to manage runtime configurations for different providers and models.

• Presets: Reusable provider templates used to generate profiles.
• Profiles: The final runtime configuration used by spawn or launch commands.

Workflow:

1. List presets: clawteam preset list
2. Generate a profile from a preset: Use clawteam preset generate-profile <preset_name> <provider> --name <profile_name>.
3. Interactive setup: Use clawteam profile wizard for a guided configuration.
4. Verify/Fix: Use clawteam profile doctor <agent> to fix onboarding states or clawteam profile test <profile_name> to run a smoke test.

Install the clawteam CLI using pip. Requires Python 3.10 or higher. For P2P transport support, install the p2p extra.

# Check if already installed
clawteam --version

# Install standard version
pip install clawteam

# Install with P2P support
pip install "clawteam[p2p]"

To initialize a team, you must first set your identity via environment variables, then spawn the team and create tasks for specific agents.

export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"

# Spawn the team
clawteam team spawn-team my-team -d "Project team" -n leader

# Create tasks for the leader and workers
clawteam task create my-team "Design system" -o leader
clawteam task create my-team "Implement feature" -o worker1
clawteam task create my-team "Write tests" -o worker2

# View the task board
clawteam board show my-team

Spawn a new agent process using a specified backend.

clawteam spawn <backend> <command...> [options]

Backends: subprocess, tmux

Options:

• --team, -t: Team name (default: "default")
• --agent-name, -n: Agent name (auto-generated if not provided)
• --agent-type: Agent type (default: "general-purpose")

Example:

clawteam spawn subprocess claude --team dev-team --agent-name bob --agent-type researcher

Global Options

Use these flags with any clawteam command:

• --json: Output JSON instead of human-readable text. Must be applied before the subcommand (e.g., clawteam --json team discover).
• --data-dir PATH: Override the default data directory (~/.clawteam).

Identity Environment Variables

Agents use these variables for identity. When using clawteam spawn, these are set automatically.

Note: Legacy OH_* aliases are also supported for compatibility.