tmux-agent

Claude가 tmux를 자율적으로 조작하여 다른 pane을 인식하고, 명령을 전송하며, 프로세스 상태를 파악합니다.

Quick Reference

작업	워크플로우	핵심 명령어
Pane 목록	WF1: Discover	`tmux list-panes -a -F "..."`
출력 캡처	WF2: Observe	`tmux capture-pane -t {target} -p`
명령 전송	WF3: Command	`tmux send-keys "cmd" Enter`
윈도우 생성	WF4: Create	`tmux new-window -n "name"`
유휴 감지	WF5: Idle	프롬프트 패턴 매칭

핵심 철학

비침투적 관찰: capture-pane으로 프로세스 방해 없이 상태 파악
간결한 전송: send-keys "cmd" Enter 형식으로 한 번에 전송
Escape 처리: 특수문자 이스케이핑 철저히 (resources/02-send-keys-safety.md)
Naming convention: 구조화된 이름으로 pane 역할 명시

Instructions

워크플로우 1: Discover (Pane 인식)

목적: 현재 tmux 세션의 모든 pane 파악

단계:

전체 pane 목록 (디렉토리 + 프로세스 포함)

tmux list-panes -a -F "#{session_name}:#{window_index}.#{pane_index} [#{pane_current_command}] #{pane_current_path}"

현재 세션만

tmux list-panes -F "#{window_index}.#{pane_index} [#{pane_current_command}] #{pane_current_path}"

특정 프로세스 필터링 (예: Claude)

tmux list-panes -a -F "#{session_name}:#{window_index}.#{pane_index}" -f "#{m:*claude*,#{pane_current_command}}"

타겟 선택: 다음 워크플로우에 사용할 pane 식별

트리거 키워드: "pane 목록", "어떤 pane", "tmux 상태"

워크플로우 2: Observe (출력 캡처)

목적: 특정 pane의 출력 내용 읽기 (프로세스 방해 없이)

단계:

기본 캡처 (현재 화면)
```
tmux capture-pane -t {target} -p
```

히스토리 포함 (최근 N줄)

tmux capture-pane -t {target} -p -S -100

ANSI 코드 포함 (디버깅용)
```
tmux capture-pane -t {target} -p -e
```
출력 분석: 에러 패턴, 완료 상태, 프롬프트 대기 여부 확인
- 패턴 참조: resources/01-capture-patterns.md

트리거 키워드: "pane 출력", "캡처", "로그 확인"

워크플로우 3: Command (명령 전송)

목적: 다른 pane에 명령어 전송 (race condition 안전)

단계:

타겟 확인: pane이 명령 대기 중인지 확인 (WF5 선행 권장)

안전한 전송 패턴

tmux send-keys -t {target} "command" Enter

특수문자 이스케이핑 (필수 확인)

# 쌍따옴표 내
tmux send-keys -t 1.0 "echo \"hello\""      # " → \"
tmux send-keys -t 1.0 "echo \$HOME"         # $ → \$

# 작은따옴표 (더 안전)
tmux send-keys -t 1.0 'echo "$HOME"'

상세 참조: resources/02-send-keys-safety.md

특수 키 전송

tmux send-keys -t {target} C-c      # Ctrl+C
tmux send-keys -t {target} C-d      # Ctrl+D
tmux send-keys -t {target} -l "C-c" # 리터럴 "C-c" 텍스트

결과 확인 (선택): WF2로 출력 캡처

트리거 키워드: "명령 전송", "send", "실행해줘", "pane에"

워크플로우 4: Create (윈도우/Pane 생성)

목적: 새 작업 공간 생성 및 초기화

단계:

새 윈도우 생성

tmux new-window -n "agent-1"              # 빈 윈도우
tmux new-window -n "agent-1" "claude"     # Claude 실행

Pane 분할

tmux split-window -h -t 0    # 수평 분할
tmux split-window -v -t 0    # 수직 분할

이름 지정

tmux rename-window -t {target} "new-name"
tmux select-pane -t {target} -T "pane-title"

Naming convention
- agent-{N}: Claude 인스턴스
- monitor-{purpose}: 모니터링 전용
- build-{project}: 빌드 프로세스
- 상세 참조: resources/03-window-management.md
초기 명령: WF3으로 초기화 스크립트 전송

트리거 키워드: "새 pane", "window 생성", "Claude 실행", "분할"

워크플로우 5: Idle Detection (유휴 상태 감지)

목적: pane이 명령 대기 중인지, 작업 중인지 판단

단계:

출력 캡처

tmux capture-pane -t {target} -p | tail -5

프롬프트 패턴 매칭

# Shell 프롬프트: $, %, ❯, >, ➜
echo "$output" | grep -qE '(\$|%|❯|➜|>)\s*$' && echo "IDLE"

# Claude 프롬프트
echo "$output" | grep -qE '(You:)\s*$' && echo "IDLE"

# 에러 패턴
echo "$output" | grep -qE '(Error:|FAIL|Traceback|panic:)' && echo "FAILED"

상태 판정
- 프롬프트 패턴 매칭 → IDLE
- 에러 패턴 → FAILED
- 그 외 → ACTIVE

트리거 키워드: "idle", "대기 중", "실행 완료", "상태 확인"

중요 원칙

타겟 검증: 명령 전송 전 pane 존재 확인

tmux list-panes -F "#{pane_id}" | grep -q "{target}"

간결한 전송: send-keys "cmd" Enter 형식 (sleep 사용 금지)
Escape 처리: 쌍따옴표 내 ", $, ` 반드시 이스케이프
에러 전파: 하위 pane 에러를 상위 호출자에게 즉시 보고
이름 표준화: Naming convention 준수로 pane 역할 명확화

Anti-patterns

❌ 위험한 패턴	✅ 안전한 패턴
`send-keys "cmd"` (Enter 누락)	`send-keys "cmd" Enter`
`send-keys "echo $VAR"`	`send-keys "echo \$VAR"` 또는 `'echo "$VAR"'`
Idle 확인 없이 명령 전송	WF5로 Idle 확인 후 전송
하드코딩된 타겟 `0.0`	WF1으로 동적 타겟 탐색

Examples

다른 pane에서 테스트 실행

User: "pane 1에서 npm test 실행하고 결과 알려줘"
→ WF1: list-panes로 1번 pane 확인
→ WF5: Idle 상태 확인
→ WF3: send-keys "npm test"
→ WF5: 완료 대기 (polling)
→ WF2: 결과 캡처 및 보고

새 Claude 인스턴스 생성 후 작업 할당

User: "새 Claude 띄워서 코드 리뷰 시켜"
→ WF4: new-window -n "agent-review" "claude"
→ WF5: Claude 준비 대기
→ WF6: 프롬프트 전송 + 응답 대기
→ WF2: 결과 캡처

병렬 작업 오케스트레이션

User: "3개 pane에서 각각 다른 테스트 실행"
→ WF1: 사용 가능한 pane 3개 식별
→ WF3 x 3: 각 pane에 테스트 명령 전송 (병렬)
→ WF5: 모든 pane 완료 대기 (polling)
→ WF2 x 3: 결과 수집 및 통합 보고

Technical Details

리소스 파일:

resources/01-capture-patterns.md: 에러/완료/프롬프트 패턴
resources/02-send-keys-safety.md: Escape 처리
resources/03-window-management.md: 레이아웃 및 이름 규칙