Claude Team MCP Server

An MCP server that allows one Claude Code session to spawn and manage a team of other Claude Code sessions via iTerm2.

Introduction

claude-team is an MCP server and a set of slash commands for allowing Claude Code to orchestrate a "team" of other Claude Code sessions. It uses the iTerm2 API to spawn new terminal sessions and run Claude Code within them.

Why?

• Parallelism: Many development tasks can be logically parallelized, but managing that parallelism is difficult for humans with limited attention spans. Claude, meanwhile, is very effective at it.
• Context management: Offloading implementation to a worker gives the implementing agent a fresh context window (smarter), and keeps the manager's context free of implementation details.
• Background work: Sometimes you want to have Claude Code go research something or answer a question without blocking the main thread of work.
• Visibility: claude-team spawns real Claude Code sessions. You can watch them, interrupt and take control, or close them out.

But, why not just use Claude Code sub-agents, you ask? They're opaque -- they go off and do things and you, the user, cannot effectively monitor their work, interject, or continue a conversation with them. Using a full Claude Code session obviates this problem.

Git Worktrees: Isolated Branches per Worker

A key feature of claude-team is git worktree support. When spawning workers with use_worktrees: true, each worker gets:

• Its own working directory - A dedicated git worktree at ~/.claude-team/worktrees/{repo-hash}/{worker-name}/
• Its own branch - Automatically created branch named {WorkerName}-{hash} (e.g., Groucho-a1b2c3)
• Shared repository history - All worktrees share the same .git database, so commits are immediately visible across workers

This means workers can make commits, run tests, and modify files without conflicting with each other or the main working directory. When work is complete, branches can be merged or submitted as PRs.

Features

• Spawn Workers: Create new Claude Code sessions in iTerm2 with multi-pane layouts
• Git Worktrees: Isolate each worker in its own branch and working directory
• Send Messages: Inject prompts into managed workers (single or broadcast)
• Read Logs: Retrieve conversation history from worker JSONL files
• Monitor Status: Check if workers are idle, processing, or waiting for input
• Idle Detection: Wait for workers to complete using stop-hook markers
• Visual Identity: Each worker gets a unique tab color and themed name (Marx Brothers, Beatles, etc.)
• Session Recovery: Discover and adopt orphaned Claude Code sessions

Requirements

• macOS with iTerm2 installed
• iTerm2 Python API enabled (Preferences → General → Magic → Enable Python API)
• Python 3.11+
• uv package manager

Installation

As Claude Code Plugin (recommended)

# Add the Martian Engineering marketplace
/plugin marketplace add Martian-Engineering/claude-team

# Install the plugin
/plugin install claude-team@martian-engineering

This automatically configures the MCP server - no manual setup needed.

From PyPI

Once published, install via:

uvx --from claude-team-mcp@latest claude-team

From Source

# Clone the repository
git clone https://github.com/Martian-Engineering/claude-team.git
cd claude-team

# Install with uv
uv sync

Configuration for Claude Code

Add to your Claude Code MCP settings. You can configure this at:

• Global: ~/.claude/settings.json
• Project: .claude/settings.json in your project directory

Using PyPI package

{
  "mcpServers": {
    "claude-team": {
      "command": "uvx",
      "args": ["--from", "claude-team-mcp@latest", "claude-team"]
    }
  }
}

Using local clone

{
  "mcpServers": {
    "claude-team": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/claude-team", "python", "-m", "claude_team_mcp"]
    }
  }
}

After adding the configuration, restart Claude Code for it to take effect.

Environment Variables

Variable	Default	Description
CLAUDE_TEAM_COMMAND	claude	Override the command used to start Claude Code in worker sessions. Useful for running alternative CLI implementations like happy.
CLAUDE_TEAM_CODEX_COMMAND	codex	Override the command used to start Codex in worker sessions. Useful for running wrapped Codex (e.g., happy codex).
CLAUDE_TEAM_PROJECT_DIR	(none)	When set, allows using "project_path": "auto" in worker configs to automatically use this path.

Example using an alternative CLI:

# For Claude Code workers
export CLAUDE_TEAM_COMMAND=happy

# For Codex workers
export CLAUDE_TEAM_CODEX_COMMAND="happy codex"

MCP Tools

Worker Management

Tool	Description
spawn_workers	Create workers in a new window with multi-pane layout (single, vertical, horizontal, quad, triple_vertical)
list_workers	List all managed workers with status
examine_worker	Get detailed worker status including conversation stats and last response preview
close_workers	Gracefully terminate one or more workers
discover_workers	Find existing Claude Code sessions running in iTerm2
adopt_worker	Import a discovered iTerm2 session into the managed registry

Communication

Tool	Description
message_workers	Send a message to one or more workers (supports wait modes: none, any, all)
read_worker_logs	Get paginated conversation history from a worker's JSONL file
annotate_worker	Add a coordinator note to a worker (visible in list_workers output)

Idle Detection

Tool	Description
check_idle_workers	Quick non-blocking check if workers are idle
wait_idle_workers	Block until workers are idle (supports "any" or "all" modes)

Utilities

Tool	Description
list_worktrees	List git worktrees created by claude-team for a repository
bd_help	Get a quick reference guide for using Beads issue tracking

Worker Identification

Workers can be referenced by any of three identifiers:

• Internal ID: Short hex string (e.g., 3962c5c4)
• Terminal ID: Prefixed iTerm UUID (e.g., iterm:6D2074A3-2D5B-4823-B257-18721A7F5A04)
• Worker name: Human-friendly name (e.g., Groucho, Aragorn)

All tools accept any of these formats.

Tool Details

spawn_workers

Arguments:
  projects: dict[str, str]     - Map of pane names to project paths
  layout: str                  - "auto", "single", "vertical", "horizontal", "quad", or "triple_vertical"
  skip_permissions: bool       - If True, start Claude with --dangerously-skip-permissions
  custom_names: list[str]      - Override automatic themed name selection
  custom_prompt: str           - Custom prompt instead of standard worker pre-prompt
  include_beads_instructions: bool - Append beads guidance to custom prompt (default: True)
  use_worktrees: bool          - Create isolated git worktree for each worker

Returns:
  sessions, layout, count, name_set, mode, use_worktrees, coordinator_guidance

Layout pane names:

• single: ["main"]
• vertical: ["left", "right"]
• horizontal: ["top", "bottom"]
• quad: ["top_left", "top_right", "bottom_left", "bottom_right"]
• triple_vertical: ["left", "middle", "right"]

message_workers

Arguments:
  session_ids: list[str]   - Worker IDs to message (accepts ID, terminal ID, or name)
  message: str             - The prompt to send
  wait_mode: str           - "none" (default), "any", or "all"
  timeout: float           - Max seconds to wait (default: 600)

Returns:
  success, session_ids, results, [idle_session_ids, all_idle, timed_out]

wait_idle_workers

Arguments:
  session_ids: list[str]   - Worker IDs to wait on
  mode: str                - "all" (default) or "any"
  timeout: float           - Max seconds to wait (default: 600)
  poll_interval: float     - Seconds between checks (default: 2)

Returns:
  session_ids, idle_session_ids, all_idle, waiting_on, mode, waited_seconds, timed_out

Slash Commands

The following slash commands are available for common workflows. Install them with:

make install-commands

Command	Description
/spawn-workers	Analyze tasks, create worktrees, and spawn workers with appropriate prompts
/check-workers	Generate a status report for all active workers
/merge-worker	Directly merge a worker's branch back to parent (for internal changes)
/pr-worker	Create a pull request from a worker's branch
/team-summary	Generate end-of-session summary of all worker activity
/cleanup-worktrees	Remove worktrees for merged branches

Usage Patterns

Basic: Spawn and Message

From your Claude Code session, spawn workers and send them tasks:

"Spawn two workers for frontend and backend work"
→ Uses spawn_workers with projects={"left": "/path/to/frontend", "right": "/path/to/backend"}
→ Returns workers named e.g. "Simon" and "Garfunkel"

"Send Simon the message: Review the React components"
→ Uses message_workers with session_ids=["Simon"]

"Check on Garfunkel's progress"
→ Uses examine_worker with session_id="Garfunkel"

Parallel Work with Worktrees

Spawn workers in isolated branches for parallel development:

"Spawn three workers with worktrees to work on different features"
→ Uses spawn_workers with use_worktrees=true
→ Creates worktrees at ~/.claude-team/worktrees/{repo}/
→ Each worker gets their own branch (e.g., "Larry-a1b2c3", "Curly-d4e5f6", "Moe-g7h8i9")

"Message all workers with their tasks, then wait for completion"
→ Uses message_workers with wait_mode="all"

"Create PRs for each worker's branch"
→ Uses /pr-worker for each completed worker

Coordinated Workflow

Use the manager to coordinate between workers:

"Spawn a backend worker to create a new API endpoint"
→ Wait for completion with wait_idle_workers

"Now spawn a frontend worker and tell it about the new endpoint"
→ Pass context from read_worker_logs of the backend worker

"Spawn a test worker to write integration tests"
→ Coordinate based on both previous workers' output

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                Manager Claude Code Session                        │
│                (has claude-team MCP server)                       │
├──────────────────────────────────────────────────────────────────┤
│                         MCP Tools                                 │
│  spawn_workers │ message_workers │ wait_idle_workers │ etc.      │
└───────────────────────────┬──────────────────────────────────────┘
                            │
               ┌────────────┼────────────┐
               ▼            ▼            ▼
         ┌──────────┐ ┌──────────┐ ┌──────────┐
         │ Groucho  │ │ Harpo    │ │ Chico    │
         │ (iTerm2) │ │ (iTerm2) │ │ (iTerm2) │
         │          │ │          │ │          │
         │  Claude  │ │  Claude  │ │  Claude  │
         │   Code   │ │   Code   │ │   Code   │
         │          │ │          │ │          │
         │ worktree │ │ worktree │ │ worktree │
         │ branch:  │ │ branch:  │ │ branch:  │
         │ Groucho- │ │ Harpo-   │ │ Chico-   │
         │ a1b2c3   │ │ d4e5f6   │ │ g7h8i9   │
         └──────────┘ └──────────┘ └──────────┘

The manager maintains:

• Session Registry: Maps worker IDs/names to iTerm2 sessions
• iTerm2 Connection: Persistent connection for terminal control
• JSONL Monitoring: Reads Claude's session files for conversation state and idle detection
• Worktree Tracking: Manages git worktrees for isolated worker branches

Development

# Sync dependencies
uv sync

# Run tests
uv run pytest

# Run the server directly (for debugging)
uv run python -m claude_team_mcp

# Install slash commands
make install-commands

Troubleshooting

"Could not connect to iTerm2"

• Make sure iTerm2 is running
• Enable: iTerm2 → Preferences → General → Magic → Enable Python API

"Session not found"

• The worker may have been closed externally
• Use list_workers to see active workers
• Workers can be referenced by ID, terminal ID, or name

"No JSONL session file found"

• Claude Code may still be starting up
• Wait a few seconds and try again
• Check that Claude Code is actually running in the worker pane

Worktree issues

• Use list_worktrees to see worktrees for a repository
• Orphaned worktrees can be cleaned up with list_worktrees + remove_orphans=true
• Worktrees are stored at ~/.claude-team/worktrees/{repo-hash}/

License

MIT

Upgrading to New Versions

After a new version is published to PyPI, you may need to force-refresh the cached version:

# Stop service first
launchctl bootout gui/$UID/com.claude-team

# Clear cache and reinstall
uv cache clean --force
uv tool install --force --refresh claude-team-mcp

# Restart service
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.claude-team.plist

This is necessary because uvx aggressively caches tool environments.