herdr로 갈아탄 후기

1. 구경만 하려다 30분 만에 갈아탔다

몇 달 전 tmux를 처음 배우기 시작했지만, 정작 실제로 쓰던 건 zellij였다. 둘 사이에 큰 차이는 없었지만, 막 배우던 tmux는 키 바인딩이 손에 익지 않았는데 zellij는 화면에 키 정보를 바로 보여주는 게 좋아서 옮겨갔다.
zellij를 쓸 때는 Tab으로 프로젝트(또는 Git Worktree)를 구분하고, Pane을 수직으로 2분할해 AI 에이전트 실행과 NeoVim을 함께 쓴다.
이때 가장 불편했던 건 어떤 에이전트가 작업을 마쳤는지 알 수 없다는 점이었다. 여러 작업을 동시에 돌려놓고도 Tab을 일일이 돌아다니면서 직접 확인해야 했다. Hook 같은 걸로 시스템 알림을 받도록 해두거나 Tab 이름을 지정해둬도, 결국 직접 열어봐야 끝났는지 알 수 있었다.

그러다 최근 Orca와 herdr를 알게 됐다. Orca는 설치해서 딱 한 번 실행해보고 바로 지웠다.
예전부터 Cmux 같은 GUI 기반 도구는 선호하지 않았는데, Orca도 Cmux에 기능을 좀 더 얹은 느낌이었다.
반면 herdr는 내가 불편해하던 부분을 시작부터 해결해줬다.
한마디로, zellij는 AI 에이전트가 등장하기 전부터 있던 터미널 멀티플렉서에 에이전트 워크플로를 얹어 쓰는 도구였다면, herdr는 처음부터 AI 에이전트 워크플로를 염두에 두고 만들어진 터미널 멀티플렉서인 것 같다.

새 키 바인딩에 익숙해져야 하는 번거로움은 있지만, 탭을 일일이 열어보지 않아도 어떤 에이전트가 끝났는지 알 수 있다는 것만으로 배울 만한 값어치는 충분했다. zellij처럼 단축키 도움말(? 키)도 잘 되어 있고, herdr는 애초에 대부분의 기능을 마우스로 제어할 수 있게 설계돼서 단축키가 기억나지 않으면 그냥 마우스를 쓰면 된다.

2. tmux·zellij와 구조는 같고, Workspace 한 층이 더 있다

사실 기본은 tmux나 zellij와 동일하다. 서버가 Session과 Pane, 그 안에서 도는 프로세스 상태를 소유하고, 클라이언트는 그 서버에 붙은 터미널 UI일 뿐이다.

zellij에 없는 herdr의 Workspace 개념은 Session → Tab → Pane 3단 구조에서 Tab을 프로젝트(repo, git worktree)나 작업 단위로 구분해서 사용하는 경우에 기존 Tab 활용 방식을 Workspace로 구분해서 사용하면 된다.

특히 에이전트 상태가 Workspace 단위로 집계되기 때문에 한 Workspace 안에 서로 다른 종류의 작업을 하는 에이전트를 욱여넣으면 herdr를 사용하는 의미가 없는 거나 마찬가지다.

Tab은 한 Workspace 안에서 화면을 더 쪼개고 싶을 때 쓰면 되는데, 정작 2주 동안 한 번도 쓰지 않았다. zellij에서 Tab이 하던 프로젝트 구분은 Workspace가 가져갔고, 그 아래는 Pane 2분할로 충분했다.

3. 탭을 열지 않아도 누가 끝났는지 보인다

zellij에서 herdr로 갈아탄 가장 큰 이유는 바로 Pane 안에서 Claude Code나 Codex를 실행하면 herdr 사이드바에 자동으로 에이전트의 상태가 감지되는 기능이었다.

멀티플렉서를 쓰면서 가장 필요했던 기능이었기 때문에 이 기능 하나만으로도 옮겨갈 이유가 충분했다.

세 Workspace에 성격이 다른 작업을 하나씩 던져두고 사이드바만 지켜본 것이다. 탭을 한 번도 옮기지 않았는데도 web이 권한 요청 때문에 멈춰 섰고, api는 먼저 끝났고, docs는 아직 돌고 있다는 게 그대로 보인다.

herdr가 에이전트를 감지하는 원리에 대해서 조사를 해봤는데 원리 자체는 단순하다.

1. Pane 안에서 실행된 에이전트의 foreground process를 보고 claude, codex, omp 같은 종류를 식별한다.
2. 에이전트별 실행 화면(UI)의 텍스트 패턴을 인식하는 규칙(detection manifest, toml)을 가지고 있다.
3. OSC(Operating System Command)라고 해서 터미널 에뮬레이터로부터 창 제목이나 진행 상태 등을 읽어온다.
4. 에이전트가 실행되는 화면에 나타나는 프롬프트나 권한 요청, 답변 등을 읽어서 Idle, Working, Blocked, Unknown 같은 상태를 추정한다.

4. 에이전트를 이름으로 부르고, 끝날 때까지 기다린다

herdr Server는 실행 중인 Session을 검사하거나 제어해야 하는 스크립트 및 에이전트를 위해 소켓 API를 제공한다. 즉 herdr의 주요 기능 대부분을 API로 제어할 수 있다는 말이다. 그리고 herdr CLI 명령어가 이 소켓 API를 Wrapping 하고 있기 때문에 CLI 명령어로도 제어할 수 있다.

이러한 기능 덕분에 에이전트를 활용한 다양한 자동화 아이디어를 구현할 수 있겠다는 생각이 들었다.

내게 가장 흥미롭고 활용해볼 만한 가치가 있겠다고 생각한 기능은 herdr agent 명령어다. Pane 안에서 돌고 있는 에이전트를 이름으로 불러서 제어하는 기능인데, 대충 이런 것들이 있다.

• agent start : 이미 있는 shell Pane을 대상으로 claude, codex, opencode 같은 에이전트를 띄운다. 새 Pane을 제멋대로 만들지 않는다는 점, 그리고 기대한 에이전트가 실제로 그 Pane을 점유했는지 확인한 뒤 interactive 상태가 될 때까지 기다려준다는 점이 핵심이다.

• agent prompt : 에이전트에게 프롬프트를 넣는다. 텍스트와 Enter를 하나의 단위로 보내고, 에이전트가 bracketed paste 모드를 켜뒀다면 붙여넣기로 인식되게 감싸서 보낸다. 그래서 여러 줄짜리 프롬프트를 넣어도 줄바꿈마다 제출되는 사고가 안 난다. --wait를 붙이면 idle, done, blocked 같은 상태가 될 때까지 서버가 대신 기다려준다.

• agent send-keys : esc, up, enter, ctrl+c 같은 키를 에이전트 UI에 보낸다.

• agent wait : 개인적으로 가장 중요하다고 느낀 명령어다. 에이전트가 특정 상태가 될 때까지 기다린다. --until로 idle, done, blocked 같은 상태를 지정하면 되는데, 핵심은 스크립트가 sleep 걸고 polling하는 방식이 아니라 herdr 서버가 상태 이벤트를 보고 기다려준다는 점이다. 호출한 순간 이미 그 상태면 즉시 반환한다.

정리하자면 zellij에서는 Pane을 열어두고 그 안의 에이전트를 내가 직접 들여다봐야 했는데, herdr에서는 에이전트를 이름으로 부르고, 프롬프트를 넣고, 완료를 기다리고, 결과를 읽는 루프를 CLI로 짤 수 있다. 터미널 멀티플렉서에 에이전트 오케스트레이션을 더했다고 볼 수 있다.

스크립트에 sleep이 한 줄도 없다는 걸 먼저 보여주고 실행한 것이다. 좌측이 agent wait에서 멈춰 있다가, 우측 에이전트가 끝나는 바로 그 순간 풀려서 다음 줄로 넘어간다.

5. HERDR_ENV는 남의 Session을 만지지 못하게 막는 표식이다

조사하다 보니 HERDR_ENV=1같은 변수를 보게 되었는데 herdr는 자신이 관리하는 Pane 안의 프로세스에 이 환경변수를 주입한다.

이건 한 마디로 “나는 지금 herdr 안에서 실행 중이다"라는 표식이다.
공식 agent skill 에서도 제어 명령을 실행하기 전에 이 값을 먼저 확인하고, 없으면 “나는 herdr 안에서 실행 중이 아니다"라고 보고 멈추도록 되어 있다.

즉 herdr 밖에서 뜬 에이전트가 우연히 로컬 herdr CLI를 호출해 내가 지금 보고 있는 Session을 잘못 만지는 상황을 막아주는 것이다.

6. 내가 쓰는 플러그인 소개

요즘 herdr의 인기가 많아지고 있어서 여러 플러그인들이 등장하고 있는데 그 중에 나름 기본적으로 쓸만하다고 생각하는 플러그인 몇 개만 소개한다.

1) vim-herdr-navigation — Neovim split과 herdr Pane을 한 세트로

Neovim의 창 분할과 herdr Pane 사이를 Ctrl + h/j/k/l 한 세트로 이동할 수 있는 내비게이션이다. 지금 포커스가 Vim split인지 herdr Pane인지 신경 쓰지 않고 하나의 앱처럼 이동할 수 있다.

나처럼 Pane을 2분할해 에이전트와 Neovim을 나란히 쓰는 사람이라면 하루에 수백 번 누르는 키라서 체감이 가장 크다.

2) herdr-worktrunk — 워크트리 생성에 붙이는 lifecycle hook

herdr에는 기본 워크트리 기능이 있다. 쉽게 말해 git worktree 명령을 herdr 안의 생성 대화 상자로 실행할 수 있는 기능인데, 특별히 대단한 건 없고 생성, 열기, 삭제만 가능하다.

나는 워크트리를 만들 때 숨김 파일 복사나 특정 명령어(예: yarn install) 실행이 함께 필요할 때가 많은데 herdr 내장 기능에는 이런 lifecycle hook이 없다. herdr-worktrunk는 herdr의 Workspace 액션을 worktrunk(wt CLI)로 넘겨주는 브릿지 플러그인이라 이 아쉬움을 채워준다.

설치하면 wt를 활용해 워크트리를 만드는 새로운 대화 상자가 뜬다. prefix+shift+g로 기본 브랜치 기준 생성/전환, prefix+shift+c로 현재 브랜치 기준, prefix+shift+d로 삭제(fzf 피커)다. 내부적으로 wt switch / wt remove를 호출하기 때문에, herdr 밖으로 나가지 않고 워크트리 생성·전환·삭제와 hook 실행까지 한 번에 끝난다.

3) herdr-browser — Pane 안에서 도는 Chromium

herdr 개발자가 만든 공식 플러그인이다.
최근에 설치해서 써봤는데 아직 엄청 유용하게 사용 중인 플러그인은 아니지만, Plannotator를 사용할때 review나 plan 결과가 localhost:<포트>로 웹 페이지가 브라우저로 열릴때 그걸 가로채서 herdr에 오른쪽 Pane으로 분할해서 띄우게 해봤다.

이 플러그인은 herdr Pane 안에 실제 Chromium을 띄우고, 동시에 그 브라우저를 CDP(Chrome DevTools Protocol) 엔드포인트로 열어준다. 즉 에이전트가 브라우저를 자동화하는 걸 내가 눈으로 보면서, 필요하면 자동화 클라이언트를 끊지 않고도 중간에 직접 마우스로 개입할 수 있다.

herdr plugin install ogulcancelik/herdr-browser --yes로 설치하고, 아래처럼 브라우저 Pane을 연다(자주 쓸 거면 키에 바인딩해두면 된다).

herdr plugin pane open --plugin official.browser --entrypoint browser --placement split --direction right

터미널 Pane에 찍힌 localhost URL을 Ctrl+클릭하면 이 브라우저에서 바로 열린다. 자동화는 CLI가 알려주는 CDP 엔드포인트에 Playwright나 Browser Use 같은 클라이언트를 붙이면 된다.

해상도가 좋지 않아서 브라우저 자체를 대체한다기 보다는 에이전트에게 웹 작업(자동화)을 시켜놓고 옆 Pane에서 진행 상황을 그대로 지켜볼 수 있다는 게 이 플러그인의 기본적인 용도이다.

7. 마치며

유행하는 도구를 자주 옮겨다니는 편은 아니고, 하나를 오래 쓰면서 숙련도를 올려가는 걸 좋아한다. 그런데도 갈아탄 건 zellij를 쓰면서 당연하게 여기고 있던 불편함을 herdr가 해결해줬기 때문이다.

이 글을 쓰는 시점에 2주쯤 썼는데, 키 바인딩은 이제 zellij를 쓸 때만큼 익숙해졌고 herdr의 기능으로 작업 방식을 더 개선할 수 있겠다는 생각이 들었다.

언젠가 더 좋은 도구가 나올 거고, 그때마다 옮겨 다니지는 않을 것이다. 그래도 새로운 도구를 한 번씩 써보는 건, 비슷하게 겪는 문제를 어떻게 해결하려고 했는지 엿볼 수 있어서 좋은 것 같다.