[기술검토] tmux 도입 및 AI 에이전트 실행 워커 연동 가능성

터미널 멀티플렉서 tmux를 자체 구축 멀티에이전트 하네스(이하 "AI 개발 파이프라인")의 헤드리스 실행 워커에 도입하는 방안을 검토했습니다. 결론: 기존 아키텍처를 바꾸지 않고 tmux 세션으로 감싸는 것만으로 SSH 끊김 대응·장시간 실행 안정화·다중 에이전트 모니터링을 단계적으로 확보할 수 있습니다.

1. tmux란?

tmux (Terminal Multiplexer) — 터미널 하나를 여러 개로 나눠서 쓰는 CLI 도구.

핵심 개념 3가지

┌─────────── tmux session ───────────────┐
│  Window 1: harness          Window 2   │
│  ┌───────────────┬─────────────────┐   │
│  │  Pane 1       │  Pane 2         │   │
│  │  claude 실행  │  tail -f logs   │   │
│  │  (진행 중)    │  (모니터링)      │   │
│  └───────────────┴─────────────────┘   │
└────────────────────────────────────────┘
     ↑ SSH 끊겨도 세션은 서버에서 계속 살아있음

Warp와의 차이

---

2. 관련 오픈소스 현황

tmux와 Claude Code를 조합한 도구들이 이미 오픈소스로 존재함.

---

3. 현재 구조와의 관계

AI 개발 파이프라인은 백엔드(Docker)와 별도로, 호스트에서 헤드리스 실행 워커(이하 "실행 워커", scripts/worker.py)가 Claude Code 프로세스를 직접 spawn 하는 구조입니다.

실행 워커 실행 흐름

현재 문제점

---

4. 도입 가능성 분석

도입 방식

tmux는 기존 실행 구조를 바꾸지 않고 감싸는 형태로 도입 가능.

활용 시나리오

시나리오 A: 실행 워커 자체를 tmux 세션으로 실행

# tmux 적용 후
tmux new-session -d -s agent-worker \
  -c "$PROJECT_DIR" \
  "python scripts/worker.py --ws-url $WS_URL"

# 재접속
tmux attach -t agent-worker

• SSH 끊겨도 실행 워커가 서버에서 계속 실행
• tmux attach로 언제든 실시간 로그 확인 가능

시나리오 B: 하네스 장시간 실행 격리

tmux window 1: /자동개발_V4 이슈-A  (진행 중)
tmux window 2: /자동검증_V4 이슈-B  (완료)
tmux window 3: /자동분석    이슈-C  (대기)

• 이슈 트래커의 이슈별로 tmux window 분리
• 실행 워커가 session_id를 추적 → 취소/상태 조회 가능
• 기존 30초 heartbeat 로직 단순화 가능

시나리오 C: 다중 에이전트 병렬 대시보드

amux 방식 참고하여 자체 구현:

실행 워커에서 tmux capture-pane 주기적 폴링 → WebSocket 브로드캐스트

---

5. 도입 권고안

단계별 로드맵

1단계 구체 구현

워커 설치 스크립트(scripts/install-worker.sh) 수정:

# tmux 설치 확인
if ! command -v tmux &> /dev/null; then
  echo "tmux가 필요합니다: brew install tmux"
  exit 1
fi

# 기존 세션 종료 후 재시작
tmux kill-session -t agent-worker 2>/dev/null || true
tmux new-session -d -s agent-worker \
  -c "$PROJECT_DIR" \
  "python scripts/worker.py --ws-url $WS_URL; read"

echo "실행 워커 시작됨 (tmux session: agent-worker)"
echo "로그 확인: tmux attach -t agent-worker"

---

6. 리스크 및 고려사항

⚠️ 대부분 경미하지만, launchd 이중화와 세션 정리 정책은 1단계 도입 시 함께 결정해야 합니다.

---

7. 요약