Launch and manage Claude Code agent team sessions.

claude-team is a CLI tool that wraps Claude Code with the experimental agent teams feature enabled. It handles:

• Interactive teammate display mode selection (auto, in-process, tmux)
• Automatic tmux session management (including iTerm2 tmux -CC control mode)
• Orchestrator system prompt injection for lead coordination
• Session lifecycle hooks (start/stop notifications)
• Automatic dependency installation via Homebrew (gum, tmux)

Note: Homebrew formula is not yet published. Use manual installation for now.

brew tap nsheaps/devsetup
brew install claude-team

git clone https://github.com/nsheaps/claude-team.git ~/.claude-team
ln -s ~/.claude-team/bin/claude-team /usr/local/bin/claude-team
ln -s ~/.claude-team/bin/ct /usr/local/bin/ct

git clone https://github.com/nsheaps/claude-team.git ~/.claude-team
echo 'export PATH="$HOME/.claude-team/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Interactive mode picker (prompts via gum)
claude-team

# Shorthand alias
ct

# Specify mode directly (skips interactive prompt)
claude-team -m tmux
claude-team --mode in-process
claude-team --mode auto

# Pass extra args to claude after --
claude-team --mode tmux -- --resume

# Non-interactive mode (uses CLAUDE_TEAM_DEFAULT_MODE or "auto")
claude-team --no-interactive

# Show help
claude-team --help

When launched, claude-team:

1. Prompts for teammate mode (or uses --mode/--no-interactive)
2. Auto-installs missing dependencies (gum, tmux) via Homebrew
3. If tmux mode is selected and you're not in a tmux session, auto-launches tmux -CC (iTerm2 control mode)
4. Launches claude with:
   • CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
   • --teammate-mode <selected>
   • --permission-mode delegate
   • --continue (resumes previous session)
   • --dangerously-skip-permissions
   • An orchestrator system prompt
   • Session start/stop lifecycle hooks

Security note: The script uses --dangerously-skip-permissions by default, which allows Claude to execute any tool without confirmation. This is intended for orchestrator sessions where the lead needs uninterrupted coordination.

Once in a team session:

Tip: When a teammate agent is unresponsive (stuck mid-turn and not processing messages), send the ESC key via tmux to interrupt its current turn and allow pending messages to propagate. Example: tmux send-keys -t <pane-id> Escape

• Claude Code (claude CLI) -- required
• gum -- interactive mode picker (auto-installed via Homebrew if missing)
• tmux -- required for tmux mode (auto-installed via Homebrew if missing)
• Homebrew -- used for auto-installing gum and tmux

# Lint shell scripts (syntax check)
mise run lint

# Format markdown with prettier
mise run fmt

# Check markdown formatting
mise run fmt-check

bin/
  claude-team      # Main launcher script
  ct               # Shorthand alias (delegates to claude-team)
  lib/
    stdlib.sh      # Shared utilities (colors, logging, check_and_install)
mise.toml          # Task runner config (lint, fmt, test)

claude-team was extracted from claude-utils. If you install claude-utils via Homebrew, claude-team is installed automatically as a dependency. You can also install claude-team standalone.

MIT