Teams & Swarms

async call(input, context) {
  const { setAppState, getAppState } = context
  const appState = getAppState()

  // Guard: one team per leader at a time
  const existingTeam = appState.teamContext?.teamName
  if (existingTeam) {
    throw new Error(
      `Already leading team "${existingTeam}". Use TeamDelete first.`
    )
  }

  // Deduplicate name
  const finalTeamName = generateUniqueTeamName(team_name)
  const leadAgentId   = formatAgentId(TEAM_LEAD_NAME, finalTeamName)

  const teamFile: TeamFile = {
    name: finalTeamName,
    createdAt: Date.now(),
    leadAgentId,
    leadSessionId: getSessionId(),
    members: [{
      agentId:      leadAgentId,
      name:         TEAM_LEAD_NAME,     // "team-lead"
      agentType:    leadAgentType,
      model:        leadModel,
      joinedAt:     Date.now(),
      tmuxPaneId:   '',
      cwd:          getCwd(),
      subscriptions: [],
    }],
  }

  await writeTeamFileAsync(finalTeamName, teamFile)
  registerTeamForSessionCleanup(finalTeamName)

  await resetTaskList(taskListId)
  await ensureTasksDir(taskListId)
  setLeaderTeamName(sanitizeName(finalTeamName))

  setAppState(prev => ({
    ...prev,
    teamContext: {
      teamName:    finalTeamName,
      teamFilePath,
      leadAgentId,
      teammates: {
        [leadAgentId]: {
          name:         TEAM_LEAD_NAME,
          color:        assignTeammateColor(leadAgentId),
          spawnedAt:    Date.now(),
          ...
        }
      }
    }
  }))
}

type TeamFile = {
  name:            string           // canonical team name
  description?:    string
  createdAt:       number           // epoch ms
  leadAgentId:     string           // "team-lead@my-team"
  leadSessionId?:  string           // session UUID of the leader
  hiddenPaneIds?:  string[]         // pane IDs moved to hidden window
  teamAllowedPaths?: TeamAllowedPath[]  // shared "always allow" edit rules
  members: Array<{
    agentId:        string   // "researcher@my-team"
    name:           string   // "researcher" — used for SendMessage
    agentType?:     string
    model?:         string
    prompt?:        string
    color?:         string
    planModeRequired?: boolean
    joinedAt:       number
    tmuxPaneId:     string   // "%3" tmux pane or iTerm session UUID
    cwd:            string
    worktreePath?:  string   // git worktree if isolated
    sessionId?:     string   // Claude session UUID
    subscriptions:  string[]
    backendType?:   'tmux' | 'iterm2' | 'in-process'
    isActive?:      boolean  // false = idle, undefined/true = running
    mode?:          PermissionMode
  }>
}

// Priority order (first match wins, cached for the session)

// 1. Running INSIDE tmux? Always use tmux.
if (await isInsideTmux()) {
  return { backend: createTmuxBackend(), isNative: true }
}

// 2. In iTerm2 with it2 CLI? Use iTerm2 (unless user prefers tmux).
if (isInITerm2()) {
  if (!getPreferTmuxOverIterm2()) {
    const it2Available = await isIt2CliAvailable()
    if (it2Available) {
      return { backend: createITermBackend(), isNative: true }
    }
  }
  // Fallback to tmux as external session if tmux is installed
  if (await isTmuxAvailable()) {
    return { backend: createTmuxBackend(), isNative: false, needsIt2Setup: true }
  }
}

// 3. Standalone terminal with tmux installed
if (await isTmuxAvailable()) {
  return { backend: createTmuxBackend(), isNative: false }
}

// 4. Nothing available → throw with platform-specific install instructions
throw new Error(getTmuxInstallInstructions())

Detection uses environment variables captured at module load time — TMUX, TMUX_PANE, TERM_PROGRAM, and ITERM_SESSION_ID — so the shell or later code overwriting them has no effect.

The it2 availability check intentionally runs it2 session list (not it2 --version) because --version exits 0 even when the iTerm2 Python API is disabled, which would cause pane splits to fail silently later.

Inside tmux (leader is in a pane): the first teammate splits the leader's pane horizontally with -l 70% so the leader keeps 30% of the window. Additional teammates split from existing teammate panes alternating vertical/horizontal, then select-layout main-vertical rebalances the right side.

Outside tmux (standalone terminal): a separate tmux server is created on a PID-scoped socket (claude-swarm-<pid>). A claude-swarm session with a swarm-view window is created. Teammates are laid out with a tiled layout. The user can attach to this session with tmux -L claude-swarm-<pid> attach.

// Internal tmux socket name prevents conflicts between multiple Claude instances
export function getSwarmSocketName(): string {
  return `claude-swarm-${process.pid}`
}

Pane creation is serialized via a promise-based mutex (acquirePaneCreationLock()) to prevent race conditions when multiple teammates are spawned in parallel. After creating each pane, the backend sleeps 200 ms to allow the shell (zsh/bash, oh-my-zsh, etc.) to finish initializing before sending the Claude command.

The iTerm2 backend tracks pane session UUIDs in a module-level array. When spawning additional teammates, it targets the last-known session UUID via it2 session split -s <uuid>.

If a user closes a pane manually (Cmd+W), the next spawn will fail with a non-zero exit code. The backend confirms the session is truly dead by running it2 session list and checking for the UUID. If it's missing, it prunes the stale ID from the array and retries. This loop is bounded — each iteration shrinks the array by one, so it terminates at worst in N+1 iterations.

while (true) {
  const splitResult = await runIt2(splitArgs)
  if (splitResult.code !== 0 && targetedTeammateId) {
    const listResult = await runIt2(['session', 'list'])
    if (!listResult.stdout.includes(targetedTeammateId)) {
      teammateSessionIds.splice(idx, 1)   // prune dead session
      continue                               // retry with next-to-last
    }
    throw new Error(...)  // systemic failure — surface it
  }
  break
}

In-process teammates run inside the leader's Node.js process. They share the API client and MCP connections but get fully isolated identity context via AsyncLocalStorage — each teammate has its own agent name, team name, color, and AbortController.

Spawn flow:

1. spawnInProcessTeammate() creates a TeammateContext and an independent AbortController (not linked to the leader's), registers an InProcessTeammateTaskState in AppState.tasks, and returns.
2. InProcessBackend.spawn() then calls startInProcessTeammate() as a fire-and-forget — the agent loop runs on the event loop in the background.
3. Kill uses abortController.abort() rather than killing a process, and the task status transitions to 'killed'.

// Teammates get an independent abort controller — interrupting the leader
// does NOT abort active teammates.
const abortController = createAbortController()

// Strip parent messages — teammates start with an empty conversation
toolUseContext: { ...this.context, messages: [] }

// Flags always forwarded if applicable:
'--dangerously-skip-permissions'  // if bypassPermissions mode active
'--permission-mode acceptEdits'   // if acceptEdits mode active
'--model <model>'                 // if set via CLI
'--settings <path>'               // if set via CLI
'--plugin-dir <dir>'              // for each inline plugin
'--teammate-mode <mode>'          // so nested spawns use same mode
'--chrome / --no-chrome'          // if set explicitly

// Env vars always set:
CLAUDECODE=1
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
CLAUDE_CODE_AGENT_COLOR=<color>   // assigned color for pane border

// Env vars forwarded if present in parent process:
CLAUDE_CODE_USE_BEDROCK  CLAUDE_CODE_USE_VERTEX  ANTHROPIC_BASE_URL
CLAUDE_CONFIG_DIR  CLAUDE_CODE_REMOTE  HTTPS_PROXY  ...

Plan mode is special: if planModeRequired=true, bypass-permissions flags are not propagated even if the leader has them set. Safety trumps convenience.

type SwarmPermissionRequest = {
  id:                  string   // "perm-<ts>-<random>"
  workerId:            string   // "researcher@my-team"
  workerName:          string
  workerColor?:        string
  teamName:            string
  toolName:            string   // e.g. "Edit"
  toolUseId:           string
  description:         string   // human-readable summary
  input:               Record<string, unknown>
  permissionSuggestions: unknown[]
  status:              'pending' | 'approved' | 'rejected'
  resolvedBy?:         'worker' | 'leader'
  resolvedAt?:         number
  feedback?:           string
  updatedInput?:       Record<string, unknown>
  permissionUpdates?:  unknown[]
  createdAt:           number
}

Write operations on the pending directory use a .lock file with proper-lockfile semantics so concurrent workers don't corrupt each other's requests.

For in-process teammates, permission prompts surface directly in the leader's terminal UI rather than going through the file system. The bridge module (leaderPermissionBridge.ts) is a module-level registry that stores the React setter functions the REPL registers at startup:

// In leaderPermissionBridge.ts — no React dependency
let registeredSetter: SetToolUseConfirmQueueFn | null = null

export function registerLeaderToolUseConfirmQueue(setter): void {
  registeredSetter = setter
}
export function getLeaderToolUseConfirmQueue() {
  return registeredSetter
}

The in-process runner calls getLeaderToolUseConfirmQueue() when it needs to present a confirmation dialog, bypassing the file-based permission system entirely.

async call(_input, context) {
  const teamName = getAppState().teamContext?.teamName

  if (teamName) {
    const teamFile = readTeamFile(teamName)
    const nonLeadMembers = teamFile.members
      .filter(m => m.name !== TEAM_LEAD_NAME)
    const activeMembers = nonLeadMembers
      .filter(m => m.isActive !== false)   // idle = false, running = true/undefined

    if (activeMembers.length > 0) {
      return { success: false, message: `Cannot cleanup: ${memberNames} still active` }
    }

    await cleanupTeamDirectories(teamName)  // teams/ + tasks/ + git worktrees
    unregisterTeamForSessionCleanup(teamName)
    clearTeammateColors()
    clearLeaderTeamName()
  }

  setAppState(prev => ({
    ...prev,
    teamContext: undefined,
    inbox: { messages: [] },   // flush queued messages
  }))
}

In list view, pressing the cycle-mode key calls cycleAllTeammateModes() which uses setMultipleMemberModes() for an atomic multi-write, preventing the TOCTOU issue of sequential single writes.

In detail view, it cycles only the selected teammate via setMemberMode(), then sends a mode_set_request message to the teammate's mailbox so the running process is notified without a file-watch poll delay.

// Atomic update of all member modes in one config.json write
setMultipleMemberModes(teamName, [
  { memberName: 'researcher', mode: 'acceptEdits' },
  { memberName: 'tester',     mode: 'acceptEdits' },
])