🐝 SwarmForge 완전 정리: 엉클 밥이 만든 tmux 멀티 에이전트

SwarmForge는 여러 AI 코딩 에이전트에게 각자의 작업 폴더와 터미널 창을 나눠 주고, 정해진 형식의 파일로만 일을 넘기게 만드는 tmux 기반 오케스트레이션 도구입니다.

AI 코딩 에이전트를 두 개 이상 같은 저장소에 붙여 보면 모델 성능과 무관한 문제가 먼저 터집니다. 두 에이전트가 같은 파일을 동시에 고치고, 누가 무엇을 끝냈는지 알 수 없으며, "이제 네 차례"라는 신호가 사람 손을 거쳐야만 전달됩니다. SwarmForge는 이 충돌과 인수인계 문제를 겨냥한 도구입니다.

만든 사람은 『클린 코드』의 저자 로버트 C. 마틴(GitHub 계정 unclebob)입니다. 저장소 소개 문구는 "여러 AI 에이전트를 조율하는 단순한 도구"이고, README는 "에이전트 무리를 신뢰할 수 있는 전문 소프트웨어 엔지니어로 바꾸는, 규율 있는 tmux 기반 오케스트레이션 플랫폼"이라고 설명합니다. 2026년 4월 17일에 공개됐고, 2026년 8월 14일 확인 기준 스타 약 2,416개, 포크 246개입니다.

SwarmForge가 푸는 문제: 에이전트끼리 부딪힌다

핵심 아이디어는 세 가지로 요약됩니다.

• 격리: 역할마다 별도의 git worktree(하나의 저장소를 여러 폴더로 동시에 체크아웃하는 git 기능)를 만들어 준다.
• 공통 규칙: 모든 에이전트가 읽는 "헌법(constitution)" 프롬프트를 둔다.
• 검증된 인수인계: 형식이 맞는 핸드오프 파일만 다음 역할에게 전달된다.

에이전트는 서로 자유롭게 말을 걸지 않습니다. 각자 자기 폴더에서 일하고, 끝나면 정해진 서식의 파일을 내보내고, 다음 역할이 그 파일을 받아 이어서 일합니다. 조립 라인에 가까운 구조라고 보면 이해가 빠릅니다.

멀티 에이전트 구조 자체가 낯설다면 멀티 에이전트 시스템 아키텍처를 먼저 읽고 오는 편이 좋습니다. 프레임워크별 차이는 멀티 에이전트 팀 완전 가이드에서 비교해 두었습니다.

2·4·6팩: 역할을 몇 개까지 나눌까

SwarmForge에서 특이한 점은 main 브랜치가 실행용이 아니라는 것입니다. main은 문서와 공용 스크립트만 담고, 실제로 돌리는 구성은 별도 브랜치에 있습니다.

브랜치	역할 구성	어울리는 작업
two-pack	coder → cleaner	작은 작업. 명세와 인수 테스트를 건너뛰는 빠른 구현·정리 루프
four-pack	specifier → coder → refactorer → architect	중간 규모. Gherkin 명세부터 시작하는 흐름
six-pack	specifier → coder → cleaner → architect → hardender → QA	큰 작업. 품질 게이트마다 담당 에이전트를 분리

specifier는 사용자의 의도를 Gherkin(사람이 읽는 문장 형태로 쓰는 테스트 명세) 인수 조건으로 바꾸고 승인을 요청합니다. coder는 승인된 조각만 TDD로 구현합니다. cleaner와 refactorer는 동작을 바꾸지 않는 정리와 커버리지 개선을 맡고, architect는 모듈 경계와 의존 방향을 봅니다. 6팩에만 있는 hardender는 뮤테이션 테스트로 테스트의 허술한 곳을 찾고, QA는 최종 검증 스크립트를 돌립니다.

이 세 개 말고 squad, adversaries 같은 실험 브랜치도 저장소에 있습니다. README에 설명이 없는 구성이므로, 처음이라면 two-pack으로 감을 잡는 편이 안전합니다.

역할 구성은 고정이 아닙니다. swarmforge/swarmforge.conf 한 줄이 창 하나입니다.

# window <역할> <에이전트> <워크트리> [task|batch] [추가 CLI 인자...]
window specifier codex master
window coder codex coder
window refactorer codex refactorer
window architect codex architect batch

master는 "새 폴더를 만들지 말고 원래 작업 디렉터리에서 돌려라"는 뜻의 예약어입니다. 나머지 역할은 .worktrees/<이름> 아래에 폴더가 생깁니다. 역할 이름마다 swarmforge/roles/<역할>.prompt 파일이 있어야 하므로, 이름을 새로 만들면 프롬프트 파일도 함께 만들어야 합니다.

설치와 실행

필요한 것은 zsh, git, tmux, Babashka(bb, Clojure 기반 스크립트 실행기), 그리고 에이전트 백엔드 하나 이상(codex, claude, copilot, grok)입니다. 전부 로컬에서 돌아갑니다.

git 원격을 추가하지 않고 실행 브랜치 압축본만 내려받는 방식을 권장합니다. 빈 디렉터리에서 실행하십시오.

BRANCH=two-pack
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" \
  | tar -xz --strip-components=1

BRANCH 값에 two-pack, four-pack, six-pack 중 하나를 넣습니다. 이 단계에서 main을 쓰면 안 됩니다. 실행 파일이 없는 문서 브랜치이기 때문입니다.

./swarm

첫 실행에서 ./swarm이 main의 공용 스크립트와 헌법 문서를 내려받아 채우고, git 저장소가 아니면 초기화한 뒤, 역할별 worktree와 tmux 세션을 만들고 창을 엽니다. 끌 때는 swarmforge.conf에 맨 처음 적힌 창을 닫으십시오. 그 창이 정리 담당이라 세션 전체가 함께 종료됩니다. 다른 창은 닫아도 감시 프로세스가 같은 tmux 세션에 다시 붙여 주므로 작업이 날아가지 않습니다.

실행 중에는 macOS의 caffeinate, 리눅스의 systemd-inhibit로 절전을 막습니다. 끄고 싶으면 SWARMFORGE_PREVENT_SLEEP=0을 설정합니다.

핸드오프 프로토콜: 에이전트는 tmux를 직접 만지지 않는다

가장 눈여겨볼 설계는 인수인계 방식입니다. 에이전트가 tmux에 직접 명령을 보내지 않습니다. handoffd.bb라는 데몬만 tmux 소켓을 쥐고, 각 역할의 보낼 편지함을 감시하다가 형식이 맞는 파일만 받는 쪽 편지함으로 복사하고, "확인해 보라"는 짧은 신호만 보냅니다.

에이전트가 쓰는 명령은 세 개뿐입니다.

• swarm_handoff.sh <초안파일> — 내보낼 인수인계를 검증하고 대기열에 넣는다
• ready_for_next.sh — 다음 일을 받는다
• done_with_current.sh — 현재 일을 끝냈다고 알린다

메시지 종류도 둘뿐입니다. 커밋을 가리키는 git_handoff와, 80자 이내 한 줄짜리 note입니다. git_handoff의 커밋 값은 정확히 10자리 16진수여야 하고, 스크립트가 실제로 그 커밋 하나로 해석되는지 확인한 뒤에야 대기열에 넣습니다. 긴 본문, 브랜치 이름, 큐 파일명, tmux 명령은 에이전트가 쓰지 않습니다. 자연어로 오가는 메시지를 최대한 줄여서 실패 지점을 없앤 구조입니다. 이런 검증 게이트 발상은 AI 코드 리뷰 자동화에서 다룬 접근과 결이 같습니다.

실행 중 상태는 .swarmforge/handoffs/ 아래 outbox, sent, failed, inbox에 남습니다. 이 파일들은 사람이 직접 고치거나 커밋하면 안 됩니다.

도입 전에 확인할 세 가지

첫째, 라이선스가 없습니다. 2026년 8월 14일 확인 기준 저장소에 LICENSE 파일이 없습니다. 라이선스 없는 공개 코드는 기본적으로 저작권자의 모든 권리가 유보된 상태입니다. 사내 도입이나 재배포를 검토한다면 이 부분을 먼저 확인해야 합니다.

둘째, 비용이 역할 수만큼 늘어납니다. 6팩은 에이전트 여섯 개가 동시에 돕니다. 같은 작업이라도 토큰 사용량과 API 요금이 그만큼 곱해집니다. 단일 에이전트로 충분한 작업에 6팩을 쓰는 것은 낭비입니다. 도구를 여러 개 비교하고 있다면 jcode 완전 가이드처럼 가벼운 대안도 함께 보는 편이 좋습니다.

셋째, 권한 플래그를 그대로 복사하지 마십시오. README의 설정 예시에는 --yolo나 --dangerously-skip-permissions 같은 인자가 등장합니다. 확인 없이 명령을 실행하게 만드는 옵션입니다. 편하지만, 여러 에이전트가 동시에 도는 환경에서는 사고 범위도 함께 커집니다. 중요한 저장소가 아닌 실험용 디렉터리에서 먼저 돌려 보십시오.

정리

SwarmForge는 "더 똑똑한 에이전트"를 파는 도구가 아닙니다. 이미 쓰고 있는 코딩 에이전트 여러 개에게 각자의 작업 공간과 정해진 인수인계 규칙을 주는 얇은 운영 계층입니다. 폴더 격리로 충돌을 없애고, 형식 검증으로 인수인계 실패를 없앤다는 두 가지 결정이 설계의 전부라고 봐도 무방합니다.

지금 시작한다면 순서는 이렇습니다. 실험용 빈 디렉터리를 만들고, two-pack을 받아 ./swarm을 실행해 창 두 개가 주고받는 모습을 직접 봅니다. 흐름이 눈에 들어오면 그때 four-pack으로 올리고, 프로젝트에 맞게 swarmforge.conf와 역할 프롬프트를 고치면 됩니다. 프로젝트 변화가 빠르므로 도입 전에는 저장소의 README와 커밋 기록을 다시 확인하십시오.