herdr 딥다이브
— 터미널에서 AI 에이전트 함대를 지휘하는 Rust 멀티플렉서

State-Runtime 분리 (AppState vs PaneRuntime)

AppState는 순수 데이터 구조체 — PTY도 없고, async도 없고, OS 호출도 없다. 모든 워크스페이스·탭·페인 레이아웃 상태가 여기 있다. PaneRuntime은 실제 PTY 프로세스, 읽기/쓰기 태스크를 담는다. 이 분리 덕분에 AppState::test_new()로 PTY 없이 단위 테스트가 가능하다. AGENTS.md가 "State is separated from runtime"을 첫 번째 원칙으로 명시한다.

에이전트 감지 — 증거 기반 TOML 매니페스트

각 에이전트마다 src/detect/manifests/claude.toml 같은 규칙 파일이 있다. 규칙은 contains(문자열 포함), regex(정규식), line_regex(줄 단위 정규식)의 AND/OR/NOT 게이트로 구성된다. 감지 엔진은 PTY 버퍼의 스냅샷을 읽어 이 규칙을 평가하고 blocked / working / done / idle을 결정한다. 매니페스트는 핫리로드가 가능해 재시작 없이 업데이트된다.

# src/detect/manifests/claude.toml 일부
id = "claude"
version = "2026.06.10.3"

[[rules]]
id = "live_blocked_form"
state = "blocked"
priority = 980
region = "after_last_horizontal_rule"
visible_blocker = true
contains = ["enter to select", "esc to cancel"]  # AND 조건
any = [
  { contains = ["tab/arrow keys to navigate"] },
]  # OR 조건

서버-클라이언트 분리 + Wire Protocol

herdr를 실행하면 자동으로 백그라운드 서버 데몬을 띄우고(없으면), TUI 클라이언트로 붙는다 (src/server/autodetect.rs). 서버는 Unix 소켓에서 대기하며 PTY 상태를 유지한다. 클라이언트는 bincode로 직렬화된 wire protocol(src/protocol/wire.rs, PROTOCOL_VERSION=15)로 서버와 통신한다. 클라이언트가 끊어져도 서버는 계속 실행 중이라 에이전트가 살아있다. --remote 플래그로 원격 서버에도 동일 프로토콜로 붙는다.

렌더 순수성 — compute_view → render(&AppState)

AGENTS.md 두 번째 원칙: "Render is pure." render()는 &AppState만 받고, 절대 상태를 변경하지 않는다. ratatui의 Frame에 그리기만 한다. 모든 기하학(geometry) 계산과 변이(mutation)는 compute_view()가 사전에 처리한다. 이 덕분에 렌더링 버그를 상태 변경과 분리해 추적할 수 있다.

herdr는 ratatui의 실전 대규모 활용 사례다. 단순한 Hello World가 아니라, 마우스 네이티브 드래그·클릭, 사이드바 스크롤, 모달 오버레이, 탭 바, 스플릿 페인 등 복잡한 레이아웃을 처리한다. src/ui/ 14개 파일을 보면 실제 프로덕션 수준 TUI 설계를 배울 수 있다.

배울 것: Layout::vertical/horizontal, Constraint, Rect 기반 레이아웃 계산, Frame 렌더링 패턴, Paragraph/List/Scrollbar 위젯 활용, 팔레트 기반 테마 시스템 (src/app/state.rs의 Palette 구조체).

각 페인에 진짜 터미널을 제공하는 핵심 기술. portable-pty로 PTY master/slave 쌍을 생성하고, slave에 에이전트 프로세스를 붙이고, master에서 출력을 읽는다. src/pty/actor.rs의 PtyIoActor는 tokio 비동기 태스크와 OS 블로킹 PTY 읽기를 연결하는 패턴을 보여준다.

배울 것: PTY 생성, 프로세스 스폰 with PTY, 비동기와 블로킹 IO 브리징 패턴, Windows ConPTY vs Unix openpty 차이.

에이전트의 터미널 출력에서 상태를 감지하려면 ANSI 이스케이프 시퀀스를 해석해야 한다. herdr는 Ghostty의 VT 파서를 Zig로 빌드해 C FFI로 호출한다. build.rs에서 Cargo 빌드 스크립트가 zig build를 실행하는 패턴, Rust에서 C 라이브러리를 연동하는 패턴을 배울 수 있다.

배울 것: Rust build.rs 커스텀 빌드 스크립트, unsafe FFI 바인딩, 크로스 컴파일(Zig cc 활용), ANSI 이스케이프 시퀀스 기초.

서버와 클라이언트가 같은 기계에서 Unix 소켓(파일 경로 기반)으로 통신한다. src/ipc.rs의 connect_local_stream / bind_local_listener가 interprocess 크레이트를 래핑한다. Wire protocol은 길이 프리픽스 + bincode 직렬화 프레임 방식이다. 최대 프레임 크기 2MB, Kitty 그래픽용 32MB 등 DoS 방지 제한도 구현돼 있다.

배울 것: Unix 도메인 소켓, 길이 프리픽스 프레이밍, bincode 직렬화, 소켓 준비 대기 패턴 (polling with timeout), Windows Named Pipe 대체 처리.

src/detect/manifests/의 TOML 파일들이 각 에이전트의 상태 인식 규칙이다. AND/OR/NOT 게이트로 복합 조건을 표현하고, 우선순위(priority)로 규칙 충돌을 해결한다. 새 에이전트 지원을 추가하려면 TOML 파일만 작성하면 된다 — Rust 코드 변경 불필요. 패턴 기반 상태 머신의 좋은 사례다.

배울 것: DSL 설계(TOML 기반 규칙), 우선순위 기반 규칙 평가, 핫리로드 패턴, 에이전트 인식 휴리스틱 (OSC 제목/진행률 시퀀스 활용).

src/api/는 외부에서 herdr를 제어하는 JSON API다. 워크스페이스 생성, 탭 열기, 페인 분할, 에이전트 상태 구독 등을 지원한다. schemars로 JSON Schema를 자동 생성해 문서화한다. 에이전트들이 이 API를 통해 자신을 오케스트레이터로 사용할 수 있다.

배울 것: 소켓 기반 RPC 설계, schemars JSON Schema 자동 생성, 이벤트 구독(subscribe) 패턴, CLI와 프로그래매틱 API 공유.

실습 1 — herdr 설치하고 에이전트 2개 동시에 돌려보기

macOS/Linux 기준으로 herdr를 설치하고, 두 개의 탭에서 각각 Claude Code와 다른 에이전트를 실행한 뒤 사이드바에서 상태가 바뀌는 것을 관찰한다.

curl -fsSL https://herdr.dev/install.sh | sh
herdr                    # 실행
# ctrl+b c : 새 탭
# 각 탭에서 에이전트 실행

확인 포인트: 에이전트가 작업 중일 때 🟡, 권한 요청 시 🔴로 바뀌는지 확인. herdr agent list로 JSON 상태 확인.

실습 2 — Socket API로 에이전트 상태 모니터링 스크립트 작성

herdr JSON API를 활용해 실행 중인 에이전트 상태를 1초마다 출력하는 셸 스크립트를 작성한다.

while true; do
  herdr agent list --json | \
    python3 -c "import sys,json; \
      agents=json.load(sys.stdin); \
      [print(f\"{a['name']}: {a['agent_status']}\") for a in agents]"
  sleep 1
done

확인 포인트: blocked인 에이전트를 발견하면 알림을 보내도록 확장해본다.

실습 3 — 새 에이전트 감지 규칙 작성 (TOML 매니페스트)

src/detect/manifests/의 기존 TOML을 참고해, 자신이 쓰는 CLI 도구의 상태 감지 규칙을 작성한다. pytest가 실행 중인지, 테스트 실패인지를 감지하는 규칙을 만들어본다.

# ~/.config/herdr/agent-detection/pytest.toml
id = "pytest"
version = "0.1.0"

[[rules]]
id = "test_running"
state = "working"
priority = 100
region = "bottom_non_empty_lines(3)"
contains = ["collecting"]

[[rules]]
id = "test_failed"
state = "blocked"
priority = 200
region = "whole_recent"
contains = ["FAILED", "ERROR"]

확인 포인트: 저장 후 herdr server reload-agent-manifests 실행. herdr agent explain <pane> --json으로 규칙 매칭 결과 확인.

실습 4 — herdr 소스 빌드 + 단위 테스트 실행

저장소를 클론하고 직접 빌드해본다. Zig 0.15가 필요하므로 Nix 개발 환경을 사용하는 것이 가장 쉽다.

git clone https://github.com/ogulcancelik/herdr
cd herdr
nix develop          # Nix 사용 시 (Zig 포함된 환경)
just test            # 단위 테스트 실행
just build           # 릴리스 빌드
./target/release/herdr --version

확인 포인트: src/app/ 내 #[cfg(test)] 블록을 찾아 PTY 없이 상태 테스트가 어떻게 동작하는지 분석. AppState::test_new() 사용 패턴 학습.

실습 5 — herdr 에이전트 스킬로 멀티 에이전트 오케스트레이션

SKILL.md를 읽고, Claude Code 에이전트 안에서 herdr tab create, herdr pane split으로 하위 에이전트 창을 열고 작업을 분배하는 프롬프트를 설계한다.

# 에이전트 스킬 설치
npx skills add ogulcancelik/herdr --skill herdr -g

# 에이전트 내에서 사용 예시
herdr tab create --workspace 1 --label "frontend"
herdr pane split --tab 1:2 --direction right
herdr agent start --name "frontend-agent" \
  --argv claude --cwd ./frontend

확인 포인트: Socket API docs(herdr.dev/docs/socket-api/)를 읽어 이벤트 구독 패턴 이해. 에이전트가 다른 에이전트의 완료를 기다리는 패턴 구현.

목표: Rust 기초 문법, 소유권·빌림 이해, ratatui로 간단한 TUI 만들기.

자료: The Rust Book (doc.rust-lang.org/book), ratatui 공식 예제 (ratatui.rs), crossterm 예제.

실습: ratatui로 카운터 TUI 앱 만들기. crossterm으로 키 입력 처리.

목표: ANSI 이스케이프 시퀀스 이해, PTY 개념 파악.

자료: XTerm Control Sequences, "The TTY demystified" (lwtm.mit.edu), portable-pty README.

실습: Python/Rust로 PTY를 열고 프로세스를 붙여서 출력 캡처하는 코드 작성.

목표: async/await, tokio 채널, 태스크 스폰 패턴 이해.

자료: tokio 공식 튜토리얼 (tokio.rs), "Programming Rust" Ch.20.

실습: tokio로 멀티 태스크 PTY 읽기/쓰기 구현. src/pty/actor.rs의 PtyIoActor 분석.

목표: Unix 도메인 소켓, bincode 직렬화, 프레이밍 패턴.

자료: "The Linux Programming Interface" Ch.57 (유닉스 도메인 소켓), bincode 문서, interprocess 크레이트 README.

실습: Unix 소켓 서버-클라이언트 간단 구현. src/protocol/wire.rs의 PROTOCOL_VERSION, MAX_FRAME_SIZE 분석.

목표: TOML 기반 규칙 DSL 설계 이해, Zig 빌드 시스템 기초, Rust-Zig FFI.

자료: AGENTS.md의 "Agent Detection Updates" 섹션, Zig 공식 문서 (ziglang.org), Rust Nomicon (FFI 챕터).

실습: 새 에이전트 매니페스트 작성. build.rs의 zig build 호출 분석. libghostty-vt의 Zig 소스 일부 읽기.

목표: herdr 이슈 트래커에서 good-first-issue 찾아 기여.

자료: CONTRIBUTING.md, AGENTS.md 전체 정독.

실습: 기존 에이전트 감지 규칙 개선 PR, 새 에이전트 매니페스트 추가, 문서 개선 등. just check로 모든 체크 통과 확인.