Claude Team MCP Server

An MCP server that allows one Claude Code session to spawn and manage a team of other Claude Code (or Codex) sessions via terminal backends (tmux or 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 terminal backends (tmux or iTerm2) 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.

Terminal Backends

claude-team supports two terminal backends:

Backend selection order:

1. CLAUDE_TEAM_TERMINAL_BACKEND environment variable (tmux or iterm)

2. Config file setting (terminal.backend)

3. Auto-detect: if TMUX env var is set, use tmux; otherwise iTerm2

Git Worktrees: Isolated Branches per Worker

A key feature of claude-team is git worktree support. When spawning workers with use_worktree: true (the default), each worker gets:

• Its own working directory - A git worktree at {repo}/.worktrees/{name}/

• Its own branch - Automatically created from the current HEAD

• Shared repository history - All worktrees share the same .git database, so commits are immediately visible across workers

Worktree naming depends on how workers are spawned:

• With a bead (issue tracker ID): {repo}/.worktrees/{bead}-{annotation}/

• Without: {repo}/.worktrees/{worker-name}-{uuid}-{annotation}/

The .worktrees directory is automatically added to .gitignore.

Codex Support

Workers can run either Claude Code or OpenAI Codex. Set agent_type: "codex" in the worker config (or set the default in the config file) to spawn Codex workers instead of Claude Code workers.

Features

• Spawn Workers: Create Claude Code or Codex sessions with multi-pane layouts

• Terminal Backends: tmux (cross-platform) and iTerm2 (macOS)

• 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

• Event Polling: Track worker lifecycle events (started, completed, stuck)

• Visual Identity: Each worker gets a unique tab color and themed name (Marx Brothers, Beatles, etc.)

• Session Recovery: Discover and adopt orphaned sessions after MCP server restarts

• HTTP Mode: Run as a persistent service with streamable-http transport

• Config File: Centralized configuration at ~/.claude-team/config.json

Requirements

• Python 3.11+

• uv package manager

• tmux backend: tmux installed (macOS or Linux)

• iTerm2 backend: macOS with iTerm2 and Python API enabled (Preferences > General > Magic > Enable Python API)

• Codex workers (optional): OpenAI Codex CLI installed

Installation

As Claude Code Plugin (recommended)

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

From PyPI

From Source

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

Using local clone

Project-level with auto project path

For project-scoped .mcp.json files, use CLAUDE_TEAM_PROJECT_DIR so workers inherit the project path:

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

Config File

claude-team reads configuration from ~/.claude-team/config.json. Manage it with the CLI:

Config Schema

Environment Variables

MCP Tools

Worker Management

Communication

Monitoring

Utilities

Worker Identification

Workers can be referenced by any of three identifiers:

• Internal ID: Short hex string (e.g., 3962c5c4)

• Terminal ID: Prefixed terminal session ID (e.g., iterm:UUID or tmux:%1)

• Worker name: Human-friendly name (e.g., Groucho, Aragorn)

All tools accept any of these formats.

Tool Details

spawn_workers

Worker assignment is determined by bead and/or prompt:

• bead only: Worker follows issue tracker workflow (mark in_progress, implement, close, commit)

• bead + prompt: Issue tracker workflow plus additional custom instructions

• prompt only: Custom task with no issue tracking

• neither: Worker spawns idle, waiting for a message

message_workers

wait_idle_workers

poll_worker_changes

HTTP Server Mode

Run claude-team as a persistent HTTP service instead of stdio:

HTTP mode enables:

• Streamable HTTP transport for MCP communication

• Worker poller that periodically snapshots worker state and emits lifecycle events

• MCP Resources for read-only session access:

  • sessions://list - List all managed sessions

  • sessions://{session_id}/status - Detailed session status

  • sessions://{session_id}/screen - Terminal screen content

Slash Commands

Install slash commands for common workflows:

Issue Tracker Support

claude-team supports both Pebbles (pb) and Beads (bd --no-db). The tracker is auto-detected by marker directories in the project root:

• .pebbles -> Pebbles

• .beads -> Beads

If both markers exist, Pebbles is selected by default. This can be overridden in the config file with issue_tracker.override. Worker prompts and coordination guidance use the detected tracker commands.

Usage Patterns

Basic: Spawn and Message

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

Parallel Work with Worktrees

Spawn workers in isolated branches for parallel development:

Issue Tracker Integration

Assign workers to issue tracker items for structured workflows:

Coordinated Workflow

Use the manager to coordinate between workers:

Architecture

The manager maintains:

• Session Registry: Maps worker IDs/names to terminal sessions

• Terminal Backend: Persistent connection to tmux or iTerm2 for terminal control

• JSONL Monitoring: Reads Claude/Codex session files for conversation state and idle detection

• Worktree Tracking: Manages git worktrees for isolated worker branches

• Event Log: Records worker lifecycle events for polling and diagnostics

Development

Troubleshooting

tmux backend

"tmux not found"

• Install tmux: brew install tmux (macOS) or apt install tmux (Linux)

• Ensure tmux is in your PATH

Workers not detected after restart

• Use discover_workers to find orphaned sessions

• Use adopt_worker to re-register them

• Sessions are matched via markers written to JSONL files

iTerm2 backend

"Could not connect to iTerm2"

• Make sure iTerm2 is running

• Enable: iTerm2 > Preferences > General > Magic > Enable Python API

General

"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 {repo}/.worktrees/

Upgrading

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

This is necessary because uvx aggressively caches tool environments.

License

MIT