DEV Community

Aloysius Chan
Aloysius Chan

Posted on • Originally published at insightginie.com

OpenClaw Skill: Claude Team - Orchestrating Parallel Development with AI Workers

#news #insights #ginie #openclaw

What is the Claude Team Skill?

The Claude Team skill is an MCP (Model Context Protocol) server that enables
you to spawn and manage teams of Claude Code sessions through iTerm2. This
powerful tool allows you to orchestrate multiple AI workers simultaneously,
each with their own terminal pane, optional git worktree, and the ability to
be assigned specific tasks or beads issues.

Why Use Claude Team for Development?

Claude Team offers several compelling advantages for modern development
workflows:

  • Parallelism : Fan out work to multiple agents working simultaneously on different tasks
  • Context Isolation : Each worker maintains fresh context, keeping your coordinator session clean
  • Visibility : Real Claude Code sessions you can watch, interrupt, or take over as needed
  • Git Worktrees : Each worker can operate in an isolated branch, enabling safe parallel development

Important Usage Rule

NEVER make code changes directly. Always spawn workers for code changes.
This ensures your context remains clean and provides proper git workflow with
worktrees.

Prerequisites

Before using Claude Team, ensure you have:

  • macOS with iTerm2 (Python API enabled: Preferences → General → Magic → Enable Python API)
  • claude-team MCP server configured in ~/.claude.json

Core Tools and Commands

Spawning Workers

The primary function is spawning workers with specific configurations:

mcporter call claude-team.spawn_workers \
workers=\
'
[{
"project_path": "/path/to/repo",
"bead": "cp-123",
"annotation": "Fix auth bug",
"use_worktree": true,
"skip_permissions": true
}]
'
\
layout="
auto
"
Enter fullscreen mode Exit fullscreen mode

Key worker configuration fields:

  • project_path: Required. Path to repository or "auto" (uses CLAUDE_TEAM_PROJECT_DIR)
  • bead: Optional beads issue ID — worker follows beads workflow
  • annotation: Task description shown on badge, used in branch name
  • prompt: Additional instructions if no bead assigned
  • use_worktree: Create isolated git worktree (default: true)
  • skip_permissions: Start with --dangerously-skip-permissions (default: false)

Layout Options

  • "auto": Reuse existing claude-team windows, split into available space
  • "new": Always create fresh window (1-4 workers in grid layout)

Managing Workers

Listing Workers 

mcporter call claude-team.list_workers
mcporter call claude-team.list_workers status_filter="
ready
"
Enter fullscreen mode Exit fullscreen mode

Status values include: spawning, ready, busy, closed.

Messaging Workers 

mcporter call claude-team.message_workers \
session_ids='[
"Groucho"
]'
\
message="
Please also add unit tests
"
\
wait_mode="
none
"
Enter fullscreen mode Exit fullscreen mode

Wait modes: "none" (fire and forget), "any" (wait for any worker idle), "all"
(wait for all workers idle).

Checking and Waiting for Completion 

# Quick poll

mcporter call claude-team.check_idle_workers session_ids='[

"Groucho","Harpo"

]'


  
  
  Blocking wait




mcporter call claude-team.wait_idle_workers \

session_ids='[

"Groucho","Harpo"

]'

\

mode="

all

"

\

timeout=600
Enter fullscreen mode Exit fullscreen mode




Reading Worker Logs


mcporter call claude-team.read_worker_logs \

session_id="

Groucho

"

\

pages=2
Enter fullscreen mode Exit fullscreen mode




Examining Worker Status


mcporter call claude-team.examine_worker session_id="

Groucho

"
Enter fullscreen mode Exit fullscreen mode




Closing Workers


mcporter call claude-team.close_workers session_ids='[

"Groucho","Harpo"

]'
Enter fullscreen mode Exit fullscreen mode




Workflow Examples

Assigning a Beads Issue 

# 1. Spawn worker with bead assignment

mcporter call claude-team.spawn_workers \

workers='[

{

"project_path": "/Users/phaedrus/Projects/myrepo",

"bead": "proj-abc",

"annotation": "Implement config schemas",

"use_worktree": true,

"skip_permissions": true

}]

'


  
  
  2. Worker automatically:




  
  
  - Creates worktree with branch named after bead




  
  
  - Runs bd show proj-abc to understand the task




  
  
  - Marks issue in_progress




  
  
  - Implements the work




  
  
  - Closes the issue




  
  
  - Commits with issue reference




  
  
  3. Monitor progress




mcporter call claude-team.check_idle_workers session_ids='[

"Groucho"

]'

mcporter call claude-team.read_worker_logs session_id="

Groucho

"



  
  
  4. When done, close and merge




mcporter call claude-team.close_workers session_ids='[

"Groucho"

]'



  
  
  Then: git merge or cherry-pick from worker's branch
Enter fullscreen mode Exit fullscreen mode




Parallel Fan-Out


# Spawn multiple workers for parallel tasks

mcporter call claude-team.spawn_workers \

workers='[

{"project_path": "auto", "bead": "cp-123", "annotation": "Auth module"},

{"project_path": "auto", "bead": "cp-124", "annotation": "API routes"},

{"project_path": "auto", "bead": "cp-125", "annotation": "Unit tests"}

]'

\

layout="

new

"


  
  
  Wait for all to complete




mcporter call claude-team.wait_idle_workers \

session_ids='[

"Groucho","Harpo","Chico"

]'

\

mode="

all

"



  
  
  Review and close




mcporter call claude-team.close_workers \

session_ids='[

"Groucho","Harpo","Chico"

]'
Enter fullscreen mode Exit fullscreen mode




Best Practices

  1. Use beads : Assign bead IDs so workers follow proper issue workflow
  2. Use worktrees : Keeps work isolated, enables parallel commits
  3. Skip permissions : Workers need skip_permissions: true to write files
  4. Monitor, don't micromanage : Let workers complete, then review
  5. Merge carefully : Review worker branches before merging to main
  6. Close workers : Always close when done to clean up worktrees

HTTP Mode for Persistent Operation

For persistent server operation, claude-team can run as an HTTP server. This
keeps the MCP server running continuously with persistent state, avoiding cold
starts.

Starting the HTTP Server 

# From the claude-team directory

uv run python -m claude_team_mcp --http --port 8766


  
  
  Or specify the directory explicitly




uv run --directory /path/to/claude-team python -m claude_team_mcp --http --port 8766
Enter fullscreen mode Exit fullscreen mode




mcporter.json Configuration

Create ~/.mcporter/mcporter.json:

{

"mcpServers": {

"claude-team": {

"transport": "

streamable-http

",

"url": "

http://127.0.0.1:8766/mcp

",

"lifecycle": "

keep-alive

"

}

}

}
Enter fullscreen mode Exit fullscreen mode




Benefits of HTTP Mode

  • Persistent state : Worker registry survives across CLI invocations
  • Faster responses : No Python environment startup on each call
  • External access : Can be accessed by cron jobs, scripts, or other tools
  • Session recovery : Server tracks sessions even if coordinator disconnects

Connecting from Claude Code

Update your .mcp.json to use HTTP transport:

{

"mcpServers": {

"claude-team": {

"transport": "

streamable-http

",

"url": "

http://127.0.0.1:8766/mcp

"

}

}

}
Enter fullscreen mode Exit fullscreen mode




Worker Identification

Workers can be referenced by any of:

  • Internal ID : Short hex string (e.g., 3962c5c4)
  • Terminal ID : iterm:UUID format
  • Worker name : Human-friendly name (e.g., Groucho, Aragorn)

Conclusion

The Claude Team skill transforms how you can approach development by enabling
true parallel AI-assisted coding. By orchestrating multiple workers, each with
their own context and worktree, you can dramatically accelerate development
workflows while maintaining code quality and proper git practices. Whether
you're tackling a single complex issue or fanning out to multiple parallel
tasks, Claude Team provides the infrastructure to make AI-assisted development
more efficient and manageable.

Skill can be found at:
team/SKILL.md>

Top comments (0)