tmux와 Claude Code: 세션, send-keys, 그리고 한계선

TL;DR Highlight

tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

Who Should Read

Claude Code 에이전트를 여러 개 동시에 돌리면서 tmux 세션 관리에 시간을 쓰고 있는 개발자

Core Mechanics

claude --worktree --tmux 한 줄이면 된다
- 최신 Claude Code는 git worktree와 tmux 세션을 한 번에 만들어 준다.
- --tmux는 --worktree 없이는 에러가 난다.
- iTerm2에서는 tmux 대신 네이티브 패널을 쓰므로 스크립트로 제어하려면 --tmux=classic을 붙여야 한다.
세션은 작업이 아니라 repo 단위로
repo마다 tmux 세션 하나를 만들고 이름도 repo 이름으로 짓는 방식을 권한다.
- 작업은 세션 안의 window로 나눈다.
- new-session -A는 있으면 붙고 없으면 만든다.
send-keys는 글자와 키 이름을 헷갈린다
Enter, C-c, Escape, Space 같은 단어가 단독 인자로 오면 키 입력으로 처리된다.
- 프롬프트 문자열은 -l 옵션으로 보내고 Enter는 따로 보내야 한다.
- 에이전트 입력창은 텍스트와 Enter가 같은 프레임에 오면 Enter를 삼키므로 사이에 sleep 0.3을 둔다.
읽기는 capture-pane, 로그는 pipe-pane
capture-pane -p -J는 줄바꿈된 줄을 이어 붙여서 grep이 어긋나지 않게 해 준다.
- pipe-pane은 pane 출력을 파일로 계속 흘려 보낸다.

Community Reactions

tmux는 계속 쓸 만하다는 의견
- tmux나 screen은 10분만 배워도 시간을 크게 아끼는 투자라는 의견이 있었다.
- 세션 하나를 tmux로 열어 두고 iTerm에서 서브에이전트를 탭으로 띄우게 한 뒤 상태는 메인 에이전트에게 물어봤더니 잘 됐다는 경험이 있었다.
tmux 대신 쓰는 도구들
herdr로 갈아탔더니 열린 세션이 한눈에 보여서 tmux 세션 관리 부담이 줄었다는 경험이 여러 건 있었다.
- 영속성만 필요해서 shpool을 쓴다는 사람도 있었다.
- 직접 멀티플렉서를 만들어 쓴다는 댓글도 많았다(seance, zmx, workmux, agent-deck 등).
설정과 유지보수 부담에 대한 경험
1월부터 8월까지 tmux에서 Claude Code를 쓰다가 설정 손보는 일이 너무 많아 ChatGPT 데스크톱 앱으로 옮겼다는 경험이 있었다.
- 세션이 많으면 컨텍스트 전환 피로가 커서 활성 세션을 2개로 줄이려 한다는 의견이 있었다.
글에 대한 반응
사실상 crystl 광고라는 지적이 있었다.
- 요즘 에이전트는 --resume을 지원해서 세션 유실 방지 목적은 많이 약해졌다는 의견이 있었다.

How to Apply

agent() 셸 함수로 repo별 세션 만들기
- 오늘 ~/.zshrc에 tmux new-session -A -s 이름 -c 디렉터리를 감싼 함수를 넣는다.
- 세션 이름은 basename에서 .을 -로 바꿔서 쓴다.
- tmux ls로 세션 목록이 repo별로 나오는지 확인한다.
send-keys 호출을 -l, sleep, Enter 3단계로 바꾸기
스크립트에서 에이전트에 프롬프트를 넣는 곳을 찾아 send-keys -l로 본문만 보낸다.
- sleep 0.3 뒤 Enter를 따로 보낸다.
- 프롬프트 안의 세미콜론은 \;로 이스케이프한다.
capture-pane -J로 상태 스크립트 만들기
상태 표시줄에 쓸 스크립트에서 각 pane의 마지막 8줄을 capture-pane -p -J로 읽는다.
- 승인 대기와 작업 중 문구를 자기 에이전트 버전에 맞게 고쳐 넣는다.
- 버전이 바뀌면 문구가 깨지므로 업그레이드 때 다시 확인한다.
에이전트가 4개를 넘으면 도구 교체를 판단하기
승인 대기를 놓치는 일이 잦으면 tmux 위에 에이전트 전용 도구를 얹을지 비교한다.
- 원격 서버와 SSH 용도는 tmux -A로 계속 쓴다.

Try It

복사해서 바로 해보기

# tmux 터미널에 그대로 붙여넣기 (Claude Code 세션을 pane으로 띄워 둔 상태에서 실행)

# 1) 세션과 window 만들고 에이전트 띄우기
tmux new-session -d -s api -c ~/code/api
tmux new-window -t api -n auth -c ~/code/api
tmux send-keys -t api:auth "claude" Enter

# 2) 프롬프트 보내기 (본문은 -l, Enter는 따로)
PROMPT="run the test suite and fix what fails"
tmux send-keys -t api:auth -l "$PROMPT"
sleep 0.3
tmux send-keys -t api:auth Enter

# 3) 화면 읽기: 마지막 30줄, 줄바꿈 이어 붙임
tmux capture-pane -p -J -S -30 -t api:auth

# 이어서 해 볼 것: pipe-pane으로 로그 저장
mkdir -p ~/agent-logs
tmux pipe-pane -o -t api:auth 'cat >> ~/agent-logs/api-auth.log'

Terminology

tmux터미널 안의 터미널 관리자다. 창을 닫아도 그 안의 프로세스가 서버에 남아 있어서 다시 붙을 수 있다.

send-keys다른 pane에 키보드로 치듯 글자를 넣는 명령이다. 스크립트가 에이전트 입력창에 대신 타이핑해 주는 방식이다.

capture-panepane에 보이는 화면이나 스크롤백을 텍스트로 뽑는 명령이다. 화면을 캡처해서 읽는 것과 비슷하다.

git worktree같은 repo를 폴더 여러 개에 나눠 체크아웃하는 기능이다. 에이전트마다 다른 브랜치를 맡겨도 서로 파일이 충돌하지 않는다.

pty프로그램이 터미널이 붙어 있다고 믿게 해 주는 가짜 터미널이다. tmux 서버가 이걸 쥐고 있어서 창을 닫아도 에이전트가 계속 돈다.