4,872
Claude Code로 기능을 구현하고, 다른 terminal에서는 Codex로 리뷰를 받는 상황을 생각해 보겠습니다. Agent가 늘면 코드를 작성하는 일뿐 아니라 누가 작업 중이고 누가 내 답을 기다리는지 확인하는 일도 중요해집니다.
이 문제를 다루는 Herdr는 무엇이고, 원래 어떤 방식으로 사용했을까요? 먼저 Herdr의 개념·주요 기능·기본 사용법을 살펴본 다음, 새 native 앱에서도 이어지는 작업 방식과 달라진 부분을 구분하겠습니다. 마지막에는 LLM 호출 없이 실행 유지와 상태 표시를 직접 확인합니다.
Herdr는 여러 terminal과 coding agent를 프로젝트별로 정리하고, 작업을 계속 실행하면서 상태를 확인하는 terminal workspace manager입니다. 원래는 기존 terminal 안에서 사용하는 TUI로 제공됐습니다. Terminal multiplexer란 하나의 terminal 환경 안에 여러 terminal을 띄우고 나누어 관리하는 도구이며, Herdr는 여기에 coding agent의 상태를 파악하는 기능을 더합니다.[7][9][11]
예를 들어 한 프로젝트에서 Claude Code를 실행한 pane, 개발 서버를 띄운 pane, 테스트 로그를 보는 pane을 함께 둘 수 있습니다. 다른 프로젝트는 별도 workspace로 나눕니다. 이 구성은 사용 예시이며, Herdr가 프로젝트 작업을 자동으로 분담하거나 코드 충돌을 해결한다는 뜻은 아닙니다.[7]
Herdr는 새 LLM도, Claude Code나 Codex를 대체하는 coding agent도 아닙니다. 평소 사용하던 agent가 실제 terminal에서 일하게 하고, 그 terminal이 어디에 있고 어떤 상태인지 관리하는 실행 환경에 가깝습니다. 기존 TUI의 공식 표현도 “the runtime your coding agents live on”입니다.[11]
공식 설명과 기능을 다음 세 가지 원칙으로 이해할 수 있습니다. 이는 문서를 바탕으로 정리한 해석입니다.[7][9][11]
claude, codex 같은 CLI를 실행합니다.[8][11]💡 Herdr의 핵심은 agent 수를 무조건 늘리는 것이 아닙니다. 여러 작업을 실행할 때 프로젝트 맥락, 실행 수명, 사람의 개입 시점을 한곳에서 관리하는 데 있습니다.[7][9]
Workspace는 프로젝트를 담는 상위 공간이고, tab은 그 안의 작업 화면이며, pane은 실제 terminal입니다. 하나의 tab을 좌우·상하 pane으로 나눌 수 있고, 마우스로 선택·크기 조절하거나 키보드로 이동할 수 있습니다.[7][8]
구성 예시: 결제 API workspace 안에 구현, 리뷰, 서버·로그 tab을 두고, 구현 tab에는 agent와 테스트 terminal을 나란히 둡니다. 이는 프로젝트 폴더의 코드나 Git branch를 자동으로 격리한다는 뜻은 아닙니다.
TUI는 지원 agent의 process·화면 규칙과 선택적 integration 등을 활용해 작업 중인지, 사용자 입력을 기다리는지 파악합니다. 완료 상태와 입력 대기를 sidebar에 모아 보여 주는 것이 일반적인 terminal 분할에서 한 걸음 더 나아간 부분입니다. 다만 새롭거나 낯선 prompt는 잘못 분류될 수 있어, 상태 표시를 승인 권한으로 취급하면 안 됩니다.[9]
Background server가 terminal을 소유하므로 client를 detach한 뒤 같은 session에 다시 붙을 수 있습니다. 로컬 작업과 저장한 SSH 머신의 작업을 함께 보거나, 연결이 끊긴 원격 작업을 이어서 확인하는 기능도 기존 TUI에 있었습니다. 이때도 실제 실행이 일어나는 머신과 server가 살아 있어야 합니다.[7][11]
사람뿐 아니라 script나 agent도 pane을 만들고, 다른 agent에 입력을 전달하고, 상태를 기다리는 흐름을 구성할 수 있습니다. Herdr가 무조건 supervisor agent로 작업을 배분하는 것은 아니며, 어떤 역할을 누구에게 줄지는 사용자가 설계합니다.[11]
TUI plugin은 herdr-plugin.toml manifest와 실행할 명령으로 이루어진 workflow package입니다. 별도의 제한된 plugin 언어가 있는 것이 아니라 shell script나 프로그램이 Herdr CLI·socket API를 호출하는 방식입니다. Plugin은 사용자 권한으로 실행되는 코드이므로 신뢰 여부를 확인해야 합니다.[10]
다음은 공식 문서 기준의 사용법입니다. TUI가 이미 설치되어 있다고 가정하며, 이번 글에서 새로 설치하거나 이 절차로 실제 agent를 실행한 것은 아닙니다.[8][11]
herdr를 실행합니다. 기본 background session을 시작하거나 다시 연결합니다.[8]claude나 codex 등 평소 사용하던 agent를 실행합니다.[8]Ctrl+b를 누르고 손을 뗀 뒤 q를 누르면 detach합니다. 돌아올 때 herdr를 다시 실행합니다. Detach와 terminal 종료는 다릅니다.[8]키보드를 선호한다면 같은 prefix 방식으로 v는 오른쪽 분할, c는 새 tab, ?는 도움말입니다. 이 키는 TUI 기준이며 새 앱의 단축키와 같다고 가정하지 마십시오.[8]
기존에 하던 작업의 상당 부분은 앱에서도 할 수 있지만, 기존 TUI에 창만 씌운 제품은 아닙니다. 공식 FAQ는 native 앱을 herdr-core 위에 만든 별도 프로그램이라고 설명합니다. TUI와 앱의 실행 중인 agent는 공유되지 않습니다.[4]
hc이며 자체 화면은 그리지 않습니다.[2]hc로 helper를 실행하고 메시지를 보내거나 기다리는 흐름을 구성합니다.[2]herdr ... 명령을 앱 제어 명령으로 그대로 복사하지 않습니다. 새 환경에서는 실행·조정은 hc, 화면 배치는 herdr-app으로 역할을 구분합니다.[1][2]먼저 앱에서 프로젝트 폴더를 사용하는 space를 만들고, task마다 의미 있는 이름의 tab을 둡니다. Tab 안에서 평소 agent를 시작하고, 필요하면 테스트나 로그용 pane을 나눕니다. Mac은 Cmd+Shift+P, 다른 플랫폼은 Ctrl+Shift+P의 command palette에서 사용할 동작과 키를 확인할 수 있습니다.[1]
원격 작업이 필요할 때만 Settings → Machines에서 SSH 머신을 추가합니다. 중요한 것은 앱을 먼저 복잡하게 꾸미는 것이 아니라, 작은 작업 하나로 terminal 실행·상태 지원·종료와 재접속의 차이를 이해하는 것입니다. 아래에서는 이 마지막 부분을 실제로 확인합니다.[1]
앱은 terminal을 배치하고, core는 terminal을 실행합니다. 앱 창을 닫는 것과 pane·tab을 닫는 것은 다릅니다. 창을 닫아도 프로그램은 계속 실행되지만, pane이나 tab을 닫으면 그 안의 terminal은 종료됩니다.[1]
머신 재부팅까지 실행이 보장되는 것은 아닙니다. 공식 문서는 reboot나 core crash 뒤 보존된 pane이 같은 폴더의 새 shell로 돌아올 뿐, 이전 프로그램을 다시 실행해 주지는 않는다고 설명합니다. 정상적인 core update·restart에서 holder가 프로그램을 유지하는 동작과도 구분해야 합니다.[1][5]
SSH로 연결한 원격 머신에서는 그 머신의 core가 프로그램을 실행합니다. 로컬 창을 닫거나 노트북이 잠들어도 원격 머신과 core가 살아 있으면 원격 작업은 계속됩니다. 이 설명을 잠든 로컬 노트북에서도 연산이 계속된다는 뜻으로 읽으면 안 됩니다.[1]
새 core는 OSC 7501이라는 Program Status Protocol로 프로그램이 보내는 working, blocked, done, error 등의 상태를 저장합니다. Agent 브랜드나 화면 문자열을 보고 상태를 추정하지 않으며, 상태를 보고하지 않는 프로그램에는 상태가 없습니다.[2]
앱에서는 Working은 작업 중, Blocked는 사용자 입력 대기, Done은 다른 곳을 보는 동안 끝난 작업을 뜻합니다. 완료한 agent를 확인하면 Idle로 보일 수 있으므로, Done 배지가 사라졌다고 실패로 판단하면 안 됩니다.[1]
실무에서 얻을 교훈은 간단합니다. 프로그램의 실행 여부와 업무 상태는 별개입니다. 상태 배지는 확인할 작업을 찾는 신호이지, 코드가 정확하거나 테스트를 통과했다는 증거가 아닙니다.
hc에는 실행·읽기·메시지 전송·대기 명령이 있습니다. Agent가 helper를 시작하고 hc send로 결과를 전달하거나 hc wait --children all로 기다리는 흐름을 구성할 수 있습니다. 기본적으로 자식은 부모와 함께 종료되며, 별도로 오래 살아야 한다면 수명 정책을 명시해야 합니다.[2]
활용 제안: 구현 agent와 읽기 전용 reviewer를 나누되, 수정 가능한 파일·작업 폴더·종료 조건을 먼저 정하는 방식이 좋습니다. 이것은 이 글의 설계 제안이며, 이번 실습에서 Claude Code와 Codex의 협업을 실행한 결과는 아닙니다.
LLM 대신 상태를 보고하는 작은 Python 프로그램을 사용합니다. API key나 모델 사용료 없이 Blocked → Working → Done과 앱 재접속을 확인할 수 있습니다. 아래 코드는 이번 검증에 사용한 테스트 프로그램입니다.
공식 앱 페이지의 download 경로로 설치합니다. Apple Silicon Mac은 DMG를 Applications로 옮길 수 있습니다. 공식 배포 대상은 macOS Apple Silicon, Linux x86-64·ARM64, Windows x64이며, Linux에는 desktop session과 Vulkan driver가 필요합니다. 기존 TUI 설치와 혼동하지 마십시오.[1][4]
먼저 Settings → Privacy에서 telemetry 설정을 확인합니다. 배포판은 기본 활성화되어 있으며 끌 수 있습니다.[3]
프로젝트 밖에 빈 herdr-lab 폴더를 만들고, 그 폴더를 사용하는 새 space와 status demo tab을 만듭니다. 아래 내용을 lab_demo.py로 저장합니다. Python 3가 설치되어 있어야 합니다.
import os
import time
def status(value):
print(f"\033]7501;state={value}:app=herdr-lab\033\\", end="", flush=True)
status("blocked")
print("Herdr lab. Press Enter to start; this is not a permission prompt.", flush=True)
input()
status("working")
print(f"START pid={os.getpid()}", flush=True)
for n in range(1, 21):
print(f"TICK {n}", flush=True)
time.sleep(1)
status("done")
print("RESULT: 20 ticks completed. Press Enter to exit.", flush=True)
input()이 프로그램은 상태 protocol을 시험하는 fixture이지, 실제 AI agent가 아닙니다. 첫 Enter는 단순한 실습 시작 입력이며 권한 승인 요청이 아닙니다.
Herdr 앱 안의 해당 폴더 terminal에서 실행합니다.
python3 lab_demo.pyBlocked가 보고되는지 확인합니다.Working으로 바뀌고 START pid=..., TICK 1, TICK 2가 출력됩니다.TICK 2가 보이면 pane·tab이 아니라 앱 전체를 종료합니다. Mac에서는 앱 Quit을 사용합니다.RESULT가 이어지는지 확인합니다.첫 입력을 기다릴 때 이미 Blocked 상태이므로, 이 실습을 자동화할 경우 실제 permission dialog와 혼동하지 않아야 합니다. Agent의 진짜 승인 요청을 강제로 통과시키는 용도로 바꾸면 안 됩니다.
같은 core session을 보는 다른 terminal에서 hc ls로 실습 terminal의 address를 찾습니다. 아래 <address>는 표시된 실제 값으로 바꿉니다. 기존 작업의 ID를 추측해서 사용하지 마십시오.[2]
hc ls
hc get <address>
hc read <address> --lines 60별도 HC_SESSION으로 격리했다면 조회 명령에도 같은 session을 지정해야 합니다. Session만 나누면 config·template은 공유되므로, 자동화 시험에서는 별도 XDG config·state 경로도 사용합니다. 이는 작업 분리이며 보안 sandbox는 아닙니다.[5]
2026-11-02 KST, macOS arm64에서 Herdr 앱 0.1.11 / hc 0.1.16으로 실행했습니다. 별도 앱 home·core session·XDG 경로를 사용했고 telemetry는 껐습니다. 기존 앱과 core는 종료하지 않았습니다.
blocked → working → done 상태를 기록했습니다.t1이었고, 앱 종료 전후 Python PID는 35628로 같았습니다.TICK 6이 새로 출력됐고, 다시 연 앱이 같은 space·tab·terminal을 표시했습니다.RESULT: 20 ticks completed. Press Enter to exit.를 실제로 읽었습니다.이 결과는 한 머신의 짧은 fixture 실습입니다. UI 화면만 보고 판정하지 않고 앱의 ls, core의 get·wait·read 결과를 대조했습니다. 재부팅·절전·SSH 단절·장시간 안정성·실제 coding agent의 상태 지원은 시험하지 않았습니다.
Herdr는 layout과 mod를 파일로 관리합니다. Layout은 창 배치, mod는 panel·menu·dialog를 그리는 JavaScript 프로그램입니다. Agent에게 앱의 guide를 읽히고 필요한 UI를 수정하게 할 수 있으며, 기본 제공 파일은 복제한 뒤 수정하는 방식이 권장됩니다.[1]
활용 제안: 처음부터 대시보드를 크게 만들기보다, tab 이름 정리나 작은 작업 시간 표시처럼 범위가 좁은 변경부터 시작하는 편이 좋습니다. 이번 글에서는 mod를 설치하거나 수정하지 않았습니다.
주의할 점은 mod가 sandboxed plugin이 아니라는 사실입니다. Mod는 사용자 환경으로 명령을 실행하고 파일을 읽거나 네트워크에 접근할 수 있으며, 연결된 머신에서도 프로그램을 실행할 수 있습니다. 프로그램 실행마다 별도의 permission prompt가 뜨는 구조도 아닙니다.[3]
⚠️ Agent가 바꿀 수 있는 UI는 곧 실행 가능한 코드입니다. 외부 mod와 그것을 불러오는 layout을 검토하고, core socket을 다른 사람에게 무심코 노출하지 마십시오. Core 자체도 agent의 권한을 제한하는 sandbox가 아닙니다.[3][5]
이 글의 판단으로는 여러 프로젝트의 agent를 병렬로 쓰고, 사용자 입력을 기다리는 작업을 자주 놓친다면 시도할 가치가 있습니다. 반대로 한 terminal의 agent만 사용하거나 기존 terminal·tmux 구성이 충분하다면 새 앱을 추가할 이유부터 확인하는 편이 낫습니다.
처음에는 새 앱으로 모든 작업을 옮기지 말고, 민감한 코드가 없는 작은 작업 하나로 상태 지원과 재접속을 확인하는 방식을 권합니다. UI 정리가 코드 리뷰·테스트·권한 분리를 대신하지는 않습니다.
원격 사용은 특히 자기 환경에서 검증해야 합니다. 공개 issue #5683에는 Herdr 앱 0.1.9·core 0.1.13과 RHEL 8.10/systemd 239 조합에서 systemd-run --same-dir 때문에 연결에 실패했다는 사용자 보고가 있습니다. 이는 특정 버전·환경의 보고이며, 이번 글에서 재현하거나 모든 Linux 환경의 결함으로 확인한 결과는 아닙니다.[6]
Telemetry도 도입 판단에 포함해야 합니다. 공식 문서는 기본 활성화된 report에 버전·OS·사용량 집계 등이 포함되고 terminal text·prompt·파일 내용·경로는 포함되지 않는다고 설명합니다. 이는 제공자가 명시한 범위이며, 이번 실습에서 전송 payload를 독립 감사한 것은 아닙니다.[3]
Done을 실제 업무 성공으로 확대하지 않습니다.[2]🔬 검증 기준: 자료 확인과 실습은 2026-11-02 KST에 수행했습니다. 공식 문서는 app commit
7a449a3, core commit5a9de29를 기준으로 읽었고, 직접 실행은 설치된 앱 0.1.11·hc 0.1.16으로 별도 검증했습니다. 문서 main의 모든 기능이 해당 설치 버전에 있다고 가정하지 않았습니다. 공개 사용자 보고는 독립 재현 시험과 구분했습니다. TUI 기초 설명은 v0.9.5 release의 README와 확인일의 TUI 문서를 추가 대조했습니다. 추가한 TUI 사용법은 문서 안내이며, 앞서 수행한 native 앱 실습을 TUI 실행 결과로 바꾸어 적지 않았습니다.
[1] https://raw.githubusercontent.com/herdrdev/herdr-app/7a449a317cf77ba72b2946310af39f3ddbbf58f2/README.md — Herdr app README — inspected commit
[2] https://raw.githubusercontent.com/herdrdev/herdr-core/5a9de29b2f9b6690388a1c297a7ca8d73df7d3e2/README.md — herdr-core README — inspected commit
[3] https://raw.githubusercontent.com/herdrdev/herdr-app/7a449a317cf77ba72b2946310af39f3ddbbf58f2/docs/security.md — Herdr app security and privacy
[4] https://herdr.dev/app — Herdr native app and TUI separation
[5] https://raw.githubusercontent.com/herdrdev/herdr-core/5a9de29b2f9b6690388a1c297a7ca8d73df7d3e2/docs/security.md — herdr-core security, sessions and state
[6] https://api.github.com/repos/herdrdev/herdr/issues/5683 — User report: RHEL 8 connection failure
[7] https://herdr.dev/tui/docs/concepts — Herdr TUI v0.9.5 docs — concepts
[8] https://herdr.dev/tui/docs/quick-start — Herdr TUI v0.9.5 docs — quick-start
[9] https://herdr.dev/tui/docs/agents — Herdr TUI v0.9.5 docs — agents
[10] https://herdr.dev/tui/docs/plugins — Herdr TUI v0.9.5 docs — plugins
[11] https://raw.githubusercontent.com/herdrdev/herdr/2ecf19a92fc3a7fff75b6ce3655ef04f4625ec01/README.md — Herdr TUI v0.9.5 README — pinned release