에이전트 여러 개를 한 터미널에서, 창을 닫아도 계속 일하는 Herdr

에이전트가 여섯 개 돌아가는 중에 지금 사람을 기다리는 것은 어느 쪽일까요? 창을 하나씩 넘겨 보지 않고는 답할 수 없다면 Herdr(저장소 herdrdev/herdr)가 겨냥하는 불편이 바로 그것입니다. Rust로 만든 Apache-2.0 오픈소스이고, 공식 문서는 자신을 멀티플렉서가 아니라 런타임(runtime, 에이전트가 사는 바탕 환경)이라고 부릅니다. 에이전트마다 진짜 터미널 칸을 주고, 칸마다 “일하는 중인지, 사람을 기다리는지”를 사이드바에 모아 보여 주며, 터미널은 백그라운드 서버가 쥐고 있어서 화면을 닫아도 일이 이어집니다. 2026-10-27 기준으로 GitHub 별은 4만 6천 개 안팎, 포크 3천 7백여 개, 최신 안정판은 10월 14일의 v0.9.5이고 그 뒤로 새 정식 릴리스는 없습니다.

tmux가 하던 세션 유지는 이미 충분히 쓸 만합니다. 다만 tmux가 보는 것은 글자가 흐르는 칸일 뿐, 그 안의 프로그램이 에이전트인지 승인 질문 중인지는 모릅니다. Herdr는 그 위에 “에이전트를 아는 층”을 얹은 도구라서, 기능 목록을 나열하기보다 하루 동안 부딪힐 장면 다섯 개로 따라가 보는 편이 이해가 빠릅니다. 장면은 편집부가 공식 문서의 동작을 바탕으로 구성한 예시이고, 명령과 오류 코드, 수치는 문서에 적힌 그대로입니다.

월요일 오전, 여섯 칸 중 사람을 기다리는 하나 찾기

아침에 프로젝트 폴더에서 herdr 한 줄을 실행하는 데서 시작합니다. 설치는 홈페이지 스크립트, Homebrew, mise, Nix, 내려받은 바이너리가 있고 Windows는 PowerShell 설치기를 씁니다. 지원 환경은 Linux(x86_64, aarch64), macOS(Intel, Apple silicon), Windows(x86_64)입니다.

brew install herdr
herdr

구조는 위에서 아래로 워크스페이스(프로젝트 하나), 탭(배치 한 장), 팬(pane, 진짜 터미널), 에이전트(팬 안에서 Herdr가 알아본 프로세스) 순입니다. 팬에는 w1:p3 같은 ID가 붙고, 한번 닫힌 ID는 다시 쓰이지 않으며 ID는 서버 하나 안에서만 의미가 있습니다. 워크스페이스 줄에는 안에 든 에이전트들의 상태가 합쳐져 올라오므로, 프로젝트 여섯 개가 열려 있어도 사이드바만 훑으면 어느 프로젝트에 손이 필요한지 보입니다.

그림 1은 이런 하루의 한 순간입니다. 왼쪽 사이드바와 오른쪽 세 칸 가운데 테두리가 노랗게 켜진 곳만 보면 됩니다.

그림 1. 편집부가 문서의 동작을 바탕으로 그린 화면 예시. 리뷰어 칸이 승인 질문에서 멈췄고 사이드바에도 같은 상태가 뜬다

혼자 놓칠 일이던 승인 질문이 사이드바에 먼저 올라오는 셈입니다. 이동 선택기(prefix+g)를 연 뒤 b를 누르면 blocked 칸만, w는 working만, i는 idle만, d는 done만 걸러 보이고 a로 전체로 돌아옵니다. 알림은 [ui.toast] delivery로 Herdr 내부, 터미널, 시스템 알림 중에서 고르거나 끄고, done과 request 소리는 mp3 파일로 바꿀 수 있습니다. 설정 파일은 ~/.config/herdr/config.toml이고 herdr --default-config로 기본값을 출력, herdr server reload-config로 실행 중에 반영합니다. 마우스 입력을 터미널에 넘기려고 [ui] mouse_capture = false로 끄면 탭 클릭이나 경계 드래그 같은 Herdr의 마우스 조작은 전부 멈춥니다.

사이드바 표시를 믿어도 되는 만큼

사이드바의 상태는 추측이 아니라 세 경로 중 하나에서 옵니다. Claude Code, Codex처럼 대부분의 에이전트는 팬의 포그라운드 프로세스를 찾고 화면 아래쪽을 규칙 파일과 맞춰 읽습니다. OpenCode, Pi, Kimi, Kilo 등은 연동을 깔면 에이전트가 직접 보고하며, 이때는 화면보다 보고가 우선합니다. Command Code, Crush처럼 Herdr를 알고 스스로 상태를 보내는 에이전트도 있습니다.

그림 2는 다섯 상태가 서로 어떻게 넘어가는지입니다. 아래쪽 노란 문장이 이 도구를 쓸 때 가장 중요한 한 줄입니다.

그림 2. 상태 전이. 완료 뒤 done은 사용자가 보면 idle로 바뀐다

화면을 읽는 에이전트에 대해 Herdr는 알려진 승인·질문·권한 화면과 맞을 때만 blocked로 표시하고, 새 모양의 대화상자는 blocked 대신 idle로 보일 수 있다고 문서가 직접 밝힙니다. 그러니 “조용하다”는 표시를 “한가하다”로 읽으면 안 되고, idle은 무엇이든 승인해도 된다는 허가도 아닙니다. 낯선 질문이 떴다면 입력을 보내기 전에 화면부터 봐야 합니다. done은 끝났는데 아직 보지 않은 상태이며, 각 클라이언트가 자기 화면에서 본 완료를 따로 세기 때문에 한 클라이언트에서 확인해도 다른 클라이언트의 done 배지는 그대로일 수 있습니다. unknown은 분류하지 못했다는 뜻일 뿐 성공의 증거가 아닙니다. Antigravity와 Grok은 자체 백그라운드 작업이 남아 있어도 프롬프트로 돌아오면 idle로 셉니다.

구현 칸이 리뷰 칸에 일을 맡기는 네 번의 호출

이 도구의 차별점은 에이전트가 Herdr를 CLI와 소켓 API로 직접 조작할 수 있다는 점입니다. 구현을 맡은 왼쪽 칸의 Claude Code가 다 만든 뒤, 사람이 미리 “끝나면 옆 칸에 Codex 리뷰어를 띄워서 diff를 검토시켜 줘”라고 말해 둔 상황을 가정해 보겠습니다.

내부에서는 그림 3의 순서로 호출이 오갑니다. 세로 점선이 세 주체이고 가로 화살표가 호출입니다. 실선은 호출자가 거는 명령, 점선은 상태가 돌아오는 방향입니다.

그림 3. 한 번의 위임에 오가는 호출. 거부와 대기 시간이 걸리는 지점이 주석으로 달려 있다

생성 명령은 결과를 JSON으로 돌려주므로 칸의 ID를 추측하지 않고 응답에서 꺼내 씁니다(.result.pane.pane_id). agent start는 셸 프롬프트에 멈춰 있는 기존 칸에서만 쓸 수 있고 기본 대기는 30초이며 --timeout은 3초 초과 300초 이하입니다. agent read는 화면 읽기 방식이 recent, recent-unwrapped, visible, detection 넷이고, 로그나 긴 답은 줄바꿈을 이어 붙인 recent-unwrapped가 읽기 좋습니다. 전체 화면 에이전트(Claude Code, OpenCode)의 지난 기록은 idle일 때만 스크롤해서 가져옵니다. 이름은 [a-z][a-z0-9_-]{0,31} 형식에 살아 있는 에이전트 사이에서만 겹치지 않으면 되고, 에이전트가 끝나면 이름도 풀립니다.

실패는 표준 오류에 JSON으로 나오고 종료 코드는 1(문법 오류는 2)입니다. 문서가 이름을 붙인 오류는 아래 여섯 개입니다.

코드	언제 나오나
agent_not_ready	시작하는 동안 blocked가 감지됨
agent_blocked	상대가 이미 blocked인데 프롬프트를 보냄. 입력은 전송되지 않음
agent_prompt_stalled	프롬프트 뒤 5초 안에 working이나 blocked가 되지 않음
agent_not_running	기다리는 동안 에이전트가 다른 칸으로 옮겨 감
agent_not_idle	지난 기록을 읽어야 하는데 에이전트가 idle이 아님
timeout	호출자가 준 제한 시간이 지남

가장 실용적인 주의는 타임아웃이나 agent_prompt_stalled가 나와도 입력이 안 갔다는 증거는 아니라는 점입니다. 문서도 스킬도 같은 프롬프트를 바로 다시 보내지 말고 먼저 agent read로 확인하라고 적습니다. 같은 지시가 두 번 들어가 일이 두 번 도는 사고를 막으려는 규칙입니다. 반대로 --wait 없이 agent wait를 따로 쓰면 기본 제한 시간이 없어서 무한 대기가 될 수 있으므로 --timeout을 주는 편이 안전합니다.

리뷰어가 도중에 승인 질문에서 멈추는 경우에는 이렇게 다룹니다. 질문 내용을 읽어서 사람에게 보여 주는 것까지가 에이전트의 몫입니다.

herdr agent wait reviewer --until blocked --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 80
herdr agent send-keys reviewer esc       # 사람이 확인한 뒤에만

테스트나 개발 서버처럼 에이전트가 아닌 프로세스는 팬 명령으로 돌리고, 출력에서 원하는 줄이 나올 때까지 기다립니다. 이 대기는 에이전트 상태를 해석하지 않고 터미널 화면에서 정규식을 찾을 뿐입니다.

herdr pane run w1:p3 "just test --watch"
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000

에이전트에게 이 명령 묶음을 가르치는 것이 skills/herdr/SKILL.md입니다. npx skills add herdrdev/herdr --skill herdr -g로 깔고(-g를 빼면 현재 프로젝트에만), Herdr가 설치돼 있으면 herdr --skill로 바이너리에 든 사본을 출력할 수도 있습니다. 스킬의 안전 규칙은 세 겹입니다. HERDR_ENV=1이 없으면 Herdr 안이 아니라고 말하고 멈추며, 사용자가 Herdr를 직접 언급했을 때만 쓰고, 요구가 없으면 새 워크스페이스나 탭, 다른 폴더를 만들지 않고 현재 칸 옆에 현재 폴더로 칸을 엽니다. 백그라운드로 숨어서 도는 서브에이전트와 달리 두 에이전트의 대화가 각자 칸에 그대로 보이기 때문에, 어느 쪽이 헛돌고 있는지 사람이 바로 알아봅니다.

노트북을 덮고 퇴근한 저녁, 서버의 에이전트는 계속 돈다

사내 서버에서 에이전트를 몇 시간 돌려야 하는 날입니다. 먼저 ssh workbox로 접속이 되는지 확인한 뒤 터미널에서 직접 실행합니다.

herdr machine add workbox
herdr machine add workbox --remote-session agents --label "Build machine"

원격에 Herdr가 없으면 설치해도 되는지 묻고, 서버를 교체하는 질문의 기본 답은 No입니다. 한 기기에 세션이 여럿 돌고 있으면 고르게 하고, 두 번째 줄처럼 --remote-session으로 직접 지정할 수도 있습니다. 이후 사이드바에는 기본 세션이 workbox로, 이름 붙은 세션이 workbox/agents로(라벨을 주면 그 이름으로) 나타나고, 그 서버의 에이전트가 로컬 에이전트 목록에 함께 섞입니다. 선택한 기기는 입력과 터미널 크기를 받고 팬 화면을 보내 주지만, 선택하지 않은 기기는 상태와 알림만 보냅니다.

노트북을 덮고 집에 가도 서버의 에이전트는 서버에서 돕니다. 로컬에서 쓰던 터미널 창을 닫거나 SSH가 끊기는 경우도 마찬가지로, 터미널과 에이전트 프로세스는 백그라운드 서버가 쥐고 있고 화면은 거기에 붙는 클라이언트일 뿐이라서 prefix+q로 떼었다가 herdr로 다시 붙으면 에이전트는 멈춘 적이 없습니다. 이 점이 v0.9.4(10월 13일)에서 한층 단단해졌습니다. Linux와 macOS에서 Herdr를 띄운 셸을 닫아도 서버가 멈추지 않게 바뀌었고, 서버는 herdr server stop(이름 붙은 세션은 herdr session stop <이름>)으로만 끝납니다. 이 명령은 팬 안의 프로세스까지 끝내니 퇴근 전에 실수로 치지 않도록 주의해야 합니다.

연결이 끊겼을 때의 동작은 문서에 구체적으로 적혀 있습니다.

• 마지막으로 알려진 워크스페이스와 에이전트 상태가 흐리게 남습니다. 캐시일 뿐 실시간이 아닙니다.
• 흐려진 칸으로의 입력과 이동은 새 연결이 맺어질 때까지 막힙니다.
• 인증 실패는 ! auth, 그 밖의 연결 문제는 ! error 배지로 뜨고, ! auth는 터미널에서 herdr machine reconnect <라벨>로 SSH 인증을 마쳐야 풀립니다.
• 재접속은 자동으로 시도되고 열린 클라이언트는 약 30초마다 실패한 연결을 다시 확인하며, 반복 실패하면 재시도 간격이 최대 2분까지 늘어납니다. 배경 재접속은 프롬프트에 답하거나 서버를 설치·재시작하지 않습니다.

다음 날 아침 원격 에이전트를 부를 때는 herdr --machine workbox agent list처럼 같은 접두사를 모든 명령에 붙입니다. 로컬 ID나 --current는 원격 칸을 가리키지 않고, 서버마다 ID가 따로라 두 대가 모두 w1:p1을 가질 수 있기 때문입니다. 인증은 Herdr가 가져가지 않습니다. 저장되는 프로필에는 ID, 이름, SSH 대상, 원격 세션 이름, 사용 여부만 있고 비밀번호나 개인 키는 들어가지 않으며 OpenSSH가 그대로 맡습니다. 호스트 키 검사도 바뀌지 않고, 에이전트 포워딩은 기본으로 꺼져 있으며, 로컬의 플러그인·설정·비밀을 원격으로 복사하지도 않습니다.

홈페이지에는 “Herdr Cloud”가 곧 공개된다는 안내가 올라와 있습니다. SSH 설정 없이 내 기기를 연결하게 해 주는 서비스이고 대기자 명단을 받고 있습니다. 지금 문서에 실려 있는 연결 방법은 위의 SSH 방식이며, 이 글의 명령도 모두 그쪽 기준입니다.

정전이 난 다음 날 아침, 되살아난 것과 사라진 것

서버가 있는 방의 전원이 나갔다고 해 봅시다. 떼었다 붙이기와 서버 재시작은 결과가 전혀 다릅니다. 공식 세션 상태 문서가 정리한 경우별 차이는 아래와 같습니다.

상황	프로세스	배치	화면 기록	에이전트 대화
떼었다 다시 붙이기	계속 실행	유지	라이브 터미널 그대로	그대로
서버 재시작(정전 포함)	사라짐	복원	팬 기록을 켠 경우만	에이전트의 세션 복원이 있을 때만
업데이트(--handoff 없이)	호환되는 서버는 유지, 재시작이 필요한 서버는 멈췄다 시작해야 함	재시작 뒤 복원	팬 기록을 켠 경우만	세션 복원이 있을 때만
업데이트 --handoff 성공	유지	유지	유지	유지

정전 뒤에는 배치가 먼저 돌아옵니다. 워크스페이스, 탭, 팬, 작업 폴더가 저장본대로 복원되고 팬마다 저장된 폴더에서 새 셸이 뜹니다. 돌던 셸, 개발 서버, 테스트 프로세스는 사라졌으므로 중간 결과는 파일에 있어야 안전합니다. 대화를 잇는 마지막 단계는 조건이 있습니다. 에이전트가 세션 번호를 보고해 두었다면 그 대화를 이어 붙이고([session] resume_agents_on_restore, 기본 켜짐), 그렇지 않거나 만료된 번호면 빈 셸이 됩니다. 보고에는 연동이 필요하고 최소 연동 버전은 Claude Code 6, Codex 5, OpenCode 5, Pi 2, Copilot 2, Hermes 2, Kimi 3이며 herdr integration status로 확인합니다.

저장 방식에는 장치가 여럿 있습니다. 그림 4는 세션 폴더(herdr session list --json으로 위치를 찾음)에 놓이는 파일입니다. 노란색은 기본으로 꺼져 있는 파일입니다.

그림 4. 복원에 쓰이는 파일. 화면 기록은 pane_history = true일 때만 저장된다

화면 기록이 꺼져 있는 이유는 화면에 비밀 값이 찍혔을 수 있어서라고 문서가 밝힙니다. 켜면 저장된 배치와 정확히 일치할 때만 되돌립니다. 스냅샷은 첫 저장 직후 한 번, 이후 최대 15분에 한 번 이전 배치를 복사해 48개까지 쌓이고 배치가 안 바뀌면 중복을 만들지 않습니다. session.json이 깨져 읽히지 않으면 원본 바이트를 session-backups/에 세 개까지 남기되 자동으로 되돌리지는 않으므로, 배치가 이상하게 복원되었다면 손으로 되돌릴 수 있습니다.

최근 릴리스도 이 대목을 다듬었습니다. v0.9.4는 Mac 재시작이나 Windows 종료 때 시스템이 앱을 닫기 전에 먼저 저장해 에이전트 세션이 살아남게 했고, 저장 파일을 디스크에 다 쓴 뒤 교체해 충돌이 나도 읽을 수 없는 저장본이 생기지 않게 했습니다. Linux의 systemd-logind에서는 종료 전에 저장할 시간을 달라고 요청하지만 강제 종료나 정전 자체는 막지 못합니다. 업데이트는 herdr update가 Herdr 자체 설치기로 깐 경우에만 쓰이고 Homebrew·mise·Nix 설치는 각 패키지 관리자로 올립니다. 서버까지 새 버전으로 넘기는 --handoff는 실험 기능이며 이 세 방식과 Windows에서는 쓸 수 없습니다.

대화 복원 연동이 설정 파일에 남기는 것

대화 복원을 쓰려면 에이전트별 연동을 깝니다.

herdr integration install claude     # 설치
herdr integration status             # 설치된 버전 확인
herdr integration uninstall claude   # 제거

공식 연동 문서에 따르면 설치는 에이전트의 설정 폴더에 작은 훅 스크립트나 플러그인 파일을 쓰고 그 에이전트의 설정 파일에 Herdr 항목을 추가합니다. Claude Code는 훅 스크립트와 settings.json 항목, Codex는 훅 스크립트와 hooks.json, config.toml의 [features] hooks = true, OpenCode는 서버·TUI 플러그인 파일이고 Grok은 자기 소유 파일 한 개만 만듭니다. 제거하면 Herdr가 넣은 항목만 지우고 나머지 설정은 그대로 둡니다. 훅은 에이전트와 같은 사용자 권한으로 돌며 로컬 소켓으로 상태만 보고합니다. 10월 14일 v0.9.5는 Codex의 턴 훅 설치를 중단해 Codex 상태를 다시 화면 감지로 읽도록 바꿨으므로, 전에 Codex 연동을 깔았다면 herdr integration install codex로 갱신하라는 안내가 릴리스 노트에 있습니다.

마켓의 플러그인 1,789개 앞에서 정해 둘 권한

홈페이지는 커뮤니티 플러그인을 1,789개로 표시하고 에이전트 CLI 22개를 자동 감지한다고 적습니다. 설치 누계 1,644,092도 같은 페이지의 표시값이라 집계 방식은 공식 쪽 설명에 의존합니다. 플러그인은 herdr-plugin.toml 매니페스트와 임의의 명령(어떤 언어든)으로 이루어지고, Herdr CLI 자체가 API 구실을 합니다. 문제는 샌드박스가 없다는 점입니다. 플러그인은 사용자의 권한과 환경을 그대로 물려받고 Herdr CLI 전체를 부를 수 있으며, Herdr는 매니페스트의 형식만 검증할 뿐 코드를 심사하지 않습니다. 마켓은 herdr-plugin 주제가 붙은 공개 GitHub 저장소를 30분마다 색인한 목록이므로 많다는 것과 안전하다는 것은 별개입니다.

herdr plugin install owner/repo --ref <리비전>   # 미리보기를 읽은 뒤 확정, 리비전 고정
herdr plugin update                              # v0.9.4부터 일괄 갱신

설치 때 나오는 미리보기를 읽고, 매니페스트와 스크립트를 직접 열어 본 뒤, --ref로 리비전을 고정하는 순서입니다. 자격 증명은 플러그인 폴더 안이 아니라 전용 설정 폴더(HERDR_PLUGIN_CONFIG_DIR)에 두라는 안내도 있습니다. 개발 속도가 빠른 만큼 호환이 깨지는 일도 있었습니다. 9월 29일 v0.9.2는 Herdr 전용 팬 그래픽 API를 없앴고, 같은 날 v0.9.3이 단축키 문제를 바로잡았으며, 10월 13일 v0.9.4와 14일 v0.9.5가 이어졌습니다. 버전이 아직 0.9.x인 점과 릴리스 간격이 짧은 점은 변화가 빠르다는 신호이고, 안정성의 증거로 읽을 수 있는 것은 별의 수가 아니라 릴리스 노트의 내용입니다.

더 큰 문제는 에이전트끼리의 호출이 만드는 길입니다. 한 에이전트가 다른 에이전트의 입력창에 글을 쓸 수 있다는 것은, 웹 문서나 파일에 섞인 악의적 지시가 한 에이전트를 거쳐 다른 에이전트로 번질 길이 생긴다는 뜻이기도 합니다. Herdr는 입력을 걸러 주지 않으므로 이 방어는 에이전트의 승인 설정과 사용자의 습관에 달려 있습니다. 다행히 agent prompt는 상대가 blocked일 때 입력을 막고, 스킬은 blocked 대화상자에 사용자 확인 없이 답하지 말라고 정해 두었습니다. 승인 프롬프트를 끈 에이전트가 다른 에이전트에게 입력을 보내는 구성이 가장 조심할 구성이고, 에이전트가 다른 칸에 쓸 수 있는 범위를 현재 폴더와 현재 칸 옆으로 정해 두는 것이 먼저입니다. 원격에서는 신뢰하지 않는 호스트에 에이전트 포워딩을 켠 채 붙지 않고, 화면 기록(pane_history)을 켠 칸에서는 비밀 값을 출력하지 않아야 합니다.

공식 비교 문서는 Herdr를 앱이나 멀티플렉서가 아니라 런타임으로 규정하고, 같은 문서가 tmux·Zellij는 사람을 위한 세션 유지, Warp는 터미널 자체를 대체하는 앱, Conductor·Emdash·Superset은 worktree와 diff 검토가 핵심인 관리 앱으로 나눕니다. 이 비교는 Herdr 쪽 문서가 쓴 것이고 문서 스스로 이 열들을 경쟁자가 아니라 범주라고 설명합니다. 개발은 YC 회사 페이지에 Fall 2026 배치, 팀 1명으로 올라 있으며 Windows 설치는 별도의 “endpoint-protected” 베타 페이지로 안내됩니다. Windows에서는 herdr terminal attach와 라이브 핸드오프가 지원되지 않습니다.

여러 에이전트를 굴릴 때 병목은 모델의 속도보다 사람의 주의인 경우가 많고, Herdr가 하는 일은 그 주의를 어느 칸에 쓸지 눈에 보이게 하고 칸 사이의 심부름을 대신 해 주는 데까지입니다. 판단은 대신해 주지 않습니다. 사이드바의 blocked 칸은 사람이 읽어야 하는 질문이고, idle 칸은 쉬고 있다는 보증이 아니며, 플러그인과 연동은 내 권한으로 도는 코드입니다. 그러니 도입은 작게 시작해 볼 만합니다. 프로젝트 하나에 칸 두 개로 상태 표시와 떼었다 붙이기부터 써 보고, 에이전트끼리 호출과 연동은 필요가 생긴 뒤에 승인 설정을 정해 놓고 켜도 늦지 않습니다.