팀 & 스웜

스웜은 여러 Claude 인스턴스가 팀으로 구성되어 협업하는 멀티 에이전트 아키텍처입니다. 각 팀메이트는 독립적인 세션에서 실행되며, 메일박스를 통해 메시지를 교환하고, 권한 상태를 동기화합니다.

스웜의 핵심 구성 요소:

• TeamFile: 팀 설정 파일 (~/.claude/teams/<name>/config.json)
• 메일박스: 팀메이트 간 비동기 메시지 교환 시스템
• 백엔드: 팀메이트 프로세스를 관리하는 런타임 (tmux/iTerm2/in-process)
• 권한 동기화: 리드 세션의 권한 결정을 모든 팀메이트에 전파

TeamCreateTool은 새로운 팀을 생성하는 도구로, 다음 5단계를 순서대로 실행합니다.

1. 팀 이름 검증: 이름 충돌과 유효성을 확인
2. 설정 파일 생성: ~/.claude/teams/<name>/config.json에 팀 설정 저장
3. 백엔드 감지: 사용 가능한 백엔드(tmux/iTerm2/in-process)를 자동 감지
4. 팀메이트 스폰: 각 팀메이트를 선택된 백엔드에서 실행
5. 메일박스 초기화: 팀메이트 간 통신 채널 설정

팀메이트 프로세스를 관리하는 세 가지 백엔드가 있으며, 감지 알고리즘이 환경에 맞는 최적의 백엔드를 자동으로 선택합니다.

백엔드 감지 우선순위

1. tmux (최고 우선순위): TMUX 환경 변수가 설정되어 있으면, 즉 현재 tmux 세션 내부에 있으면 tmux 백엔드가 선택됩니다. tmux 내부에서 iTerm2를 사용해도 tmux가 우선합니다.
2. iTerm2: macOS에서 iTerm2 터미널이 활성화되어 있고 Python API가 사용 가능한 경우
3. in-process (폴백): 위 조건을 모두 만족하지 않을 때 동일 프로세스 내에서 실행

// 백엔드 감지 알고리즘
function detectBackend(): Backend {
  if (process.env.TMUX) {
    return 'tmux'     // tmux 내부 → 항상 tmux
  }
  if (isIt2CliAvailable()) {
    return 'iterm2'   // iTerm2 Python API 활성
  }
  return 'in-process' // 폴백
}

팀메이트 간 통신은 메일박스 시스템을 통해 이루어집니다. 7종의 메시지 타입이 정의되어 있으며, 각 타입은 특정 목적에 맞게 설계되었습니다.

7종 메시지 타입

• task: 새 작업 할당
• status: 상태 업데이트 요청/응답
• result: 작업 완료 결과 반환
• error: 오류 보고
• permission: 권한 동기화 메시지
• heartbeat: 생존 확인 핑
• control: 종료, 일시 중지 등 제어 명령

isActive: false의 의미

팀메이트의 isActive 플래그가 false이면 해당 팀메이트가 유휴 상태임을 의미합니다. 영구적으로 종료된 것이 아니라, 현재 턴의 작업이 종료된 상태입니다. 새로운 메시지가 메일박스에 도착하면 깨어나서 작업을 재개합니다.

리드 세션(사용자가 직접 상호작용하는 세션)에서 내린 권한 결정은 모든 팀메이트에 자동으로 전파됩니다. 사용자가 한 번 허용한 도구 실행은 다른 팀메이트가 동일한 도구를 사용할 때 다시 묻지 않습니다.

팀의 생명주기는 네 단계로 구성됩니다:

1. 생성 (Create): TeamCreateTool이 설정, 백엔드, 메일박스를 초기화
2. 실행 (Run): 팀메이트가 메일박스를 통해 작업을 수행하고 결과를 교환
3. 유휴 (Idle): 작업이 없는 팀메이트는 isActive: false로 대기
4. 삭제 (Delete): TeamDeleteTool이 모든 팀메이트 프로세스를 종료하고 리소스를 정리

TeamDeleteTool과 비정상 종료

TeamDeleteTool은 정상적인 팀 종료를 처리합니다. 그러나 Ctrl-C로 리드 세션을 강제 종료하면 TeamDeleteTool이 호출되지 않을 수 있습니다.

// 비정상 종료 시 정리 — cleanupSessionTeams()
async function cleanupSessionTeams() {
  // 1. 모든 tmux 페인 강제 종료
  await killAllPanes(sessionId)

  // 2. 팀 디렉토리 제거
  await removeTeamDir(teamName)
}