herdr 사용기 (1) | 에이전트 여러 개 돌리다 herdr에 정착한 이유

직접 만든 플러그인: Agent Title, Blueprint, 그리고 플러그인을 만들고 배포하며 겪은 일

들어가며

요즘은 Claude Code를 하나만 켜두지 않는다.

 

집에서는 사이드 프로젝트, 블로그와 노트 정리, 플러그인 개발을 각각 돌리고, 회사에서는 프로젝트 네 개를 동시에 돌릴 때도 있다.

에이전트가 하나일 때는 화면을 보고 있으면 된다.

 

그런데 셋, 넷이 되면 이야기가 달라진다.

 

일을 시켜두고 다른 창으로 넘어가면, 그 사이에 누가 끝났는지, 누가 권한을 묻느라 멈춰 있는지 알 수가 없다.

결국 탭을 하나씩 열어보며 확인하게 되고, 10분 전에 끝난 에이전트를 그제야 발견한다.

 

 

에이전트를 여러 개 돌릴 때 필요한 건 더 많은 화면이 아니라 "지금 누가 무슨 상태인지"를 한눈에 보는 것이었다.

그걸 처음 알려준 건 Orca였지만, 마우스를 많이 쓰고 무겁게 느껴져서 키보드로 다 되는 herdr에 정착했다.

그래도 남은 불편은 플러그인으로 직접 만들어 채웠고, 이 시리즈는 그 기록이다.

 

에이전트가 늘어나자 생긴 문제

 

정리해 보면 불편은 세 가지였다.

1. 누가 끝났는지 모른다. 일을 시켜두고 브라우저로 넘어가면, 끝났다는 걸 알 방법이 없다.
2. 누가 내 답을 기다리는지 모른다. 에이전트가 "이 파일 수정해도 될까요?"라고 물은 채 멈춰 있어도, 그 탭을 열기 전까지는 모른다. 일을 시킨 줄 알았는데 실제로는 아무것도 안 하고 있던 셈이다.
3. 프로젝트가 한 화면에 섞인다. 창이 늘어날수록 어떤 터미널이 어떤 프로젝트인지 헷갈린다.

1번과 2번은 결국 같은 이야기다.

에이전트의 상태가 보이지 않는다는 것.

처음엔 Orca를 썼다

이 문제를 처음 풀어준 건 Orca였다.

왼쪽에 에이전트마다 작업 중인지, 입력을 기다리는지, 끝났는지가 보이니 "뭐가 끝났고 뭐가 남았지"를 머릿속으로 관리하던 부담이 확 줄었다.

 

그때 쓴 후기가 병렬 에이전트 시대의 작업대, Orca를 써봤다이다.

 

그런데 매일 쓰다 보니 두 가지가 계속 걸렸다.

이미지 출처: HHKB 공식 사이트

 

첫째, 마우스를 너무 많이 썼다.

나는 해피해킹 키보드를 쓴다.

해피해킹 유저답게 손을 키보드 위에 두고 터미널에서 조작하는 걸 좋아한다.

그런데 Orca는 기능이 많은 만큼 클릭할 곳도 많았고, 에이전트 사이를 오갈 때마다 손이 마우스로 갔다.

 

둘째, 무겁게 느껴졌다.

정확히 측정해서 비교해 본 건 아니고 체감이다.

기능이 많은 게 한몫한다고 생각했다.

특히 IntelliJ를 같이 켜면 더 크게 와닿았다.

그렇다고 Orca가 나쁜 도구라는 말은 아니다.

특히 모바일 기능은 지금도 좋다고 느낀다.

다만 하루 종일 붙어 있는 작업 환경으로는 더 가볍고, 키보드로 다 되는 쪽이 나한테 맞았다.

herdr로 옮겼다

herdr는 스스로를 "AI 코딩 에이전트를 위한 터미널 작업 공간 관리자"(terminal workspace manager for AI coding agents)라고 소개한다.

tmux처럼 터미널 화면을 나눠 쓰는 도구인데, 처음부터 에이전트를 염두에 두고 만들어졌다는 점이 다르다.

터미널 안에서 돌아가니 키보드만으로 다 되고, macOS·Linux·Windows를 지원한다.

 

지금은 Mac에서 Ghostty + herdr, Windows에서 WezTerm + herdr 조합으로 쓴다.

세 프로젝트에서 Claude Code가 각자 돌고 있는 화면이다.

왼쪽 사이드바의 점 색이 상태다.

shop-api는 작업 중(노랑), blog는 내 답을 기다리는 중(분홍), mobile-app은 끝났지만 아직 확인하지 않음(청록).

색은 테마에 따라 다르다.

1. 에이전트 상태가 사이드바에 보인다

Orca에서 제일 좋았던 그 기능이 터미널 안에 있다.

herdr는 각 pane에서 돌아가는 에이전트를 알아보고 상태를 표시한다.

• working: 일하는 중
• blocked: 내 입력을 기다리는 중
• done: 끝났는데 아직 내가 확인하지 않음
• idle: 대기 중

특히 done과 idle을 구분해 주는 게 좋았다.

보고 있지 않은 동안 끝난 에이전트만 done으로 남기 때문에, 사이드바만 훑어도 "확인해야 할 것"이 바로 보인다.

Claude Code, Codex 같은 주요 에이전트는 따로 설정하지 않아도 알아본다.

blog의 Claude가 질문을 던지고 멈춰 있다.

이 탭을 열지 않아도 사이드바의 분홍 점으로 알 수 있다.

2. workspace, tab, pane으로 나눠 쓴다

herdr는 화면을 세 단계로 나눈다.

• workspace: 가장 큰 단위. 나는 프로젝트 하나에 workspace 하나를 쓴다.
• tab: workspace 안의 화면. 같은 프로젝트에서 하는 일이 여러 갈래일 때 나눈다.
• pane: tab 안을 다시 쪼갠 칸. 왼쪽에 에이전트, 오른쪽에 nvim이나 셸을 둔다.

사이드바 위쪽은 workspace 목록이고, 아래쪽은 workspace별로 묶은 에이전트 목록이다.

회사에서 프로젝트 네 개를 동시에 돌릴 때도 workspace만 오가면 되니 섞이지 않는다.

이 단계를 어떻게 나눠 쓰는지는 따로 한 편으로 정리하려고 한다.

3. 단축키를 마음대로 바꾸고, 원하는 동작을 붙일 수 있다

키보드로 쓰는 도구라면 단축키가 손에 맞아야 한다.

herdr는 config.toml에서 기본 단축키를 바꿀 수 있고, 단축키에 셸 명령, 팝업, 플러그인 동작을 직접 연결할 수 있다.

내 설정 일부다.

[keys]
prefix = "ctrl+a"
focus_pane_left  = ["prefix+h", "ctrl+alt+h"]   # vim처럼 h j k l로 pane 이동
focus_pane_right = ["prefix+l", "ctrl+alt+l"]
next_workspace     = "alt+j"
previous_workspace = "alt+k"
switch_workspace   = "alt+1..9"                 # 프로젝트 사이를 숫자로 바로 이동

# prefix+t: 오른쪽에 nvim pane 열기
[[keys.command]]
key = "prefix+t"
type = "shell"
command = "$HOME/.config/herdr/bin/nvim-pane.sh"

# ctrl+alt+i: 단축키 정리표 팝업
[[keys.command]]
key = "ctrl+alt+i"
type = "popup"
command = "less -R $HOME/.config/herdr/cheatsheet.txt"
width = 56
height = 28

alt+숫자로 프로젝트를 바로 넘나들고, ctrl+alt+h/j/k/l로 pane 사이를 오간다.

마우스에 손이 갈 일이 거의 없다.

4. 터미널을 닫아도 에이전트는 계속 돈다

herdr는 뒤에서 서버로 계속 돌아간다.

터미널 창을 닫거나 노트북을 덮었다가 다시 herdr를 실행하면, 에이전트는 하던 일을 이어가고 있다.

SSH로 다른 머신을 붙이면 원격 작업 공간도 같은 사이드바에 나란히 보인다.

5. 모든 것을 명령어로 다룰 수 있다

pane을 나누고, 화면 내용을 읽고, 에이전트에게 프롬프트를 보내는 일이 전부 herdr 명령어로 된다.

herdr pane list                              # 모든 pane과 에이전트 상태
herdr pane read w1:p1                        # pane 화면 읽기
herdr agent prompt w1:p1 "테스트 돌려줘"      # 에이전트에게 프롬프트 보내기

herdr 공식 사이트의 표현을 빌리면, 이 CLI는 "에이전트가 쓰는 것과 같은 표면"이다.

사람이 쓰든, 에이전트가 쓰든, 다른 프로그램이 쓰든 같은 방법으로 herdr를 조종할 수 있다.

이게 뒤에서 말할 플러그인의 바탕이 된다.

그래도 남은 불편

herdr로 큰 문제는 풀렸지만, 매일 쓰다 보니 작은 불편이 눈에 들어왔다.

• 보고 있는 탭의 에이전트는 알림이 오지 않는다. herdr의 기본 알림은 지금 보이는 탭의 에이전트는 건너뛴다. 그래서 Claude를 돌려두고 다른 앱으로 넘어가면, 끝나도 모른다.
• pane 테두리에 이름이 claude뿐이다. Claude가 다섯 개면 다섯 개 다 claude다. 어느 pane이 무슨 일을 하는지는 열어봐야 안다.
• 화면을 나누면 오른쪽 pane이 논다. 에이전트 옆에 뭔가 보조 화면을 띄우고 싶었다.
• 에이전트의 긴 설명을 결국 안 읽게 된다. 작업이 끝날 때마다 쏟아지는 긴 글을, 솔직히 다 읽지 않는다.

다행히 herdr에는 플러그인 구조가 있다.

에이전트 상태가 바뀔 때 스크립트를 실행하고, 원하는 프로그램을 pane으로 띄우고, 앞에서 본 것처럼 단축키에 플러그인 동작을 연결할 수 있다.

CLI까지 쓸 수 있으니, 불편한 건 직접 만들면 됐다.

그래서 만들었다.

불편	만든 것
pane마다 무슨 일을 하는지 모름	Agent Title: 에이전트가 스스로 작업 제목을 붙임
긴 설명을 안 읽게 됨, 오른쪽 pane이 놂	Blueprint: 에이전트가 작업을 다이어그램으로 그려 옆 pane에 띄움
보고 있는 탭은 알림이 안 옴	맥 알림 플러그인 (개인용)

Agent Title과 Blueprint는 GitHub에 공개해 두었고, 시리즈에서 하나씩 소개할 생각이다.

herdr 시작하기

curl -fsSL https://herdr.dev/install.sh | sh
herdr

작업 공간이 열리면 그 안에서 평소처럼 claude나 codex를 실행하면 된다.

사이드바에 에이전트가 나타나고 상태가 표시되기 시작한다.

자세한 사용법은 공식 문서에 있다.

마무리

에이전트를 여러 개 돌리기 시작하면서 필요해진 건 더 많은 화면이 아니라, 지금 누가 무슨 상태인지 한눈에 보는 것이었다.

그리고 나처럼 키보드에서 손을 떼고 싶지 않은 사람에게는, 그걸 터미널 안에서 해주는 herdr가 잘 맞았다.

앞으로 이 시리즈에서는 herdr를 쓰면서 쌓은 노하우와, 불편해서 직접 만든 플러그인을 차례로 공유하려고 한다.

다음 글에서는 workspace·tab·pane을 실제로 어떻게 나눠 쓰는지, 또는 첫 번째 플러그인인 Agent Title 이야기로 이어가겠다.