5.3 KiB
Herdr 사용 가이드
소개
Herdr는 "코딩 에이전트를 위한 tmux"라고 볼 수 있는 터미널 워크스페이스 매니저(agent multiplexer)입니다. 여러 AI 코딩 에이전트(Claude Code, Codex 등)를 각각 실제 터미널 pane에서 실행하면서, 어떤 에이전트가 작업 중인지 / 입력을 기다리는지(blocked) / 끝났는지를 사이드바에서 한눈에 확인할 수 있고, detach해도 백그라운드에서 계속 실행됩니다. Rust로 작성된 로컬 바이너리이며 별도의 GUI 앱이나 클라우드 계정이 필요 없습니다.
공식 사이트: herdr.dev
주요 사용사례
- 여러 에이전트를 동시에 병렬로 실행하며 상태만 사이드바에서 훑어보기
- SSH나 휴대폰으로 원격 접속해 백그라운드 세션에 이어 붙기 (detach/reattach)
- 소켓 API/CLI로 스크립트나 다른 에이전트(오케스트레이터)가 에이전트에 명령을 넣고 결과를 읽어오는 자동화
- 서버 재시작 후에도 에이전트 네이티브 세션을 복원해서 이어가기 (Claude Code, Codex 등 통합 시)
- 하나의 워크스페이스(프로젝트) 안에서 여러 개의 서로 다른 workspace/session으로 완전히 격리된 작업 공간 운용
개념 정리
| 개념 | 설명 |
|---|---|
| Session | 지속되는 Herdr 서버 하나(런타임 인스턴스). herdr는 기본 세션에 붙고, herdr --session <name>으로 named session을 launch-or-attach 할 수 있음 |
| Workspace | 세션 안의 최상위 프로젝트 컨테이너. 보통 repo/작업 단위로 하나씩 |
| Tab | workspace 안의 레이아웃 |
| Pane | 실제 터미널 하나 |
| Agent | Herdr가 pane 안에서 인식하는 프로세스 (Claude Code, Codex 등). 상태: blocked/working/done/idle/unknown |
| Channel | Herdr 바이너리 자체의 업데이트 트랙 (stable/preview) — session과 무관한 별개 개념 |
주요 단축키
prefix 키 기본값은 ctrl+b. prefix+?로 언제든 전체 목록 확인 가능.
가장 먼저 배울 5가지:
| 동작 | 키 |
|---|---|
| 새 탭 | prefix+c |
| 좌우/상하 분할 | prefix+v / prefix+minus |
| 패널 이동 | prefix+h/j/k/l |
| 워크스페이스 탐색 | prefix+w |
| detach (세션 유지) | prefix+q |
추가 자주 쓰는 것:
| 동작 | 키 |
|---|---|
| 패널 확대(zoom) | prefix+z |
| 패널 닫기 | prefix+x |
| 카피 모드 | prefix+[ |
| 다음/이전 탭 | prefix+n / prefix+p |
| 새 워크스페이스 | prefix+shift+n |
| 사이드바 토글 | prefix+b |
마우스만으로도 클릭/드래그/우클릭 메뉴로 대부분 조작 가능 (mouse-native).
실습: 세션 생성 → Claude 실행 → 소켓으로 프롬프트 전달 → 결과 확인
1. 현재 디렉터리를 cwd로 하는 새 세션 new_session 생성
cd <현재 작업 디렉터리>
herdr --session new_session
Herdr의 세션은 launch-or-attach 모델이라 이 한 줄로 세션이 없으면 생성하고 동시에 attach까지 됩니다.
2. 생성된 세션에서 Claude 실행
attach된 pane 안에서:
claude
(테스트용으로 권한 프롬프트를 건너뛰려면 claude --dangerously-skip-permissions. 신뢰된 환경에서만 사용 권장.)
3. 다른 터미널에서 herdr 명령으로 프롬프트 전달 (직접 타이핑 아님)
새 터미널에서 에이전트 목록과 pane_id 확인:
herdr --session new_session agent list
herdr --session new_session agent get claude
텍스트 입력 + Enter 제출을 원자적으로 수행:
herdr --session new_session pane run <pane_id> "정렬 프로그램을 작성해줘"
4. Claude의 결과 화면 출력
완료될 때까지 기다렸다가 읽기:
herdr --session new_session wait agent-status <pane_id> --status idle
herdr --session new_session pane read <pane_id> --source recent --lines 150
현재 화면만 바로 보기:
herdr --session new_session pane read <pane_id> --source visible --lines 80
--session new_session을 매번 붙이는 대신 export HERDR_SESSION=new_session으로 환경변수를 설정하면 이후 명령에서 생략 가능합니다.
참고: 다중 workspace 간 에이전트 제어
Herdr의 소켓 API/CLI는 workspace 단위로 격리되지 않고 세션 전체가 하나의 소켓을 공유합니다. pane_id가 w1:p1 같은 전역 ID라서, 지금 어느 workspace에 있든 다른 workspace의 에이전트를 agent send, agent read, wait agent-status, pane run 등으로 그대로 제어할 수 있습니다.
herdr workspace create --cwd ~/project --label claude-test
herdr workspace list # 방금 만든 workspace_id 확인
herdr agent start claude-test --workspace <workspace_id> -- claude
herdr agent send claude-test "테스트"
herdr wait agent-status claude-test --status idle