ogulcancelik/herdr

herdr.dev · 설치 · 빠른 시작 · 지원되는 에이전트 (agents) · 통합 (integrations) · 설정 · 소켓 API (socket api)

v.0.4.0.mp4

터미널에서 실행되는 에이전트 멀티플렉서 (agent multiplexer).

워크스페이스 (workspaces), 탭 (tabs), 창 (panes). 마우스 네이티브 지원: 클릭, 드래그, 분할. 모든 에이전트의 상태를 한눈에 확인: 차단됨 (blocked), 작업 중 (working), 완료 (done). 분리 (detach) 및 재연결 (reattach) 시에도 에이전트는 계속 실행됩니다. GUI 앱도, Electron도, Mac 전용 네이티브 래퍼 (native wrapper)도 아닙니다. 누군가의 해석이 아닌, 에이전트 자체의 터미널을 직접 보게 됩니다.

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

또는 Homebrew로 설치:

brew install herdr

또는 릴리스 (releases)에서 바이너리 (binary)를 다운로드하세요. Linux 또는 macOS가 필요합니다.

작업이 진행 중인 디렉토리에서 Herdr를 시작하세요:

herdr

Herdr는 하나의 백그라운드 세션 서버 (background session server)를 시작하거나 연결합니다. ctrl+b를 누른 후 shift+n을 눌러 워크스페이스를 생성하세요. 루트 창 (root pane)에서 에이전트를 실행합니다. ctrl+b를 누른 후 v 또는 minus를 눌러 창을 분할하고, ctrl+b를 누른 후 c를 눌러 탭을 생성하며, ctrl+b를 누른 후 w를 눌러 워크스페이스를 전환하세요.

ctrl+b q를 눌러 클라이언트 (client)를 분리하세요. 서버와 창 프로세스 (pane processes)는 계속 실행됩니다. 다른 터미널을 열고 다시 herdr를 실행하여 재연결하세요.

서버 (Server)와 클라이언트 (client). 기본적으로 herdr는 백그라운드 서버에 연결됩니다. 분리 (detaching)는 클라이언트만 종료합니다. herdr server stop은 기본 서버를 중지하고 해당 창들을 종료합니다. 완전히 분리된 런타임 상태 (runtime state)가 필요한 경우, 이름이 지정된 세션 (Named sessions)은 별도의 서버 네임스페이스 (namespaces)를 가집니다: herdr session attach work, herdr session stop work, herdr session list를 사용하세요.

워크스페이스 (Workspaces), 탭 (tabs), 창 (panes). 워크스페이스는 프로젝트 수준의 컨테이너입니다. 탭은 워크스페이스 내부의 창들을 그룹화합니다. 창 (panes)은 재작성된 에이전트 뷰가 아닌 실제 터미널 프로세스 (terminal processes)입니다.

복사 (Copy). Herdr는 사이드바가 아닌 창 (pane)의 텍스트를 복사합니다. 창 내부에서 드래그하여 선택하거나, 단어 또는 토큰을 더블 클릭하거나, 키보드 복사 모드를 위해 prefix+[를 누르세요. 복사 모드에서는 h/j/k/l, w/b/e, {/}로 이동하고, v 또는 Space로 선택을 시작하며, y 또는 Enter로 복사하고, q 또는 Esc로 나갑니다. PuTTY 및 일부 SSH 터미널에서는 Shift를 누른 채로...

터미널 자체의 선택 기능을 사용하려면 Shift를 누른 채로 드래그하고, Shift를 누른 상태에서 마우스 오른쪽 버튼을 클릭하여 붙여넣습니다.

업데이트 및 복구 (Update and restore). herdr update는 새로운 바이너리 (binary)를 설치하지만, 실행 중인 서버는 중지되거나 핸드오프 (handoff)될 때까지 기존 프로세스를 계속 사용합니다. 기본 세션의 경우 herdr server stop을 실행하거나, 이름이 지정된 세션의 경우 herdr session stop <name>을 실행한 다음 Herdr를 다시 시작하세요. herdr update --handoff는 실험적인 기능으로, 개발 서버와 같은 포그라운드 프로세스 (foreground processes)를 포함하여 라이브 창 (live panes)을 기존 서버에서 새 서버로 이동하려고 시도합니다. 만약 [session] resume_agents_on_restore = true가 활성화되어 있고 현재 공식 통합 기능 (official integrations)이 설치되어 있다면, 지원되는 에이전트 창 (agent panes)은 서버 재시작 또는 업데이트 후 자체 에이전트 세션 (agent sessions)으로부터 재시작될 수 있습니다.

키 바인딩 (Keybindings). Herdr는 명시적인 키 바인딩 (keybinding) 문자열을 사용합니다. prefix+n은 설정된 프리픽스 (prefix)를 누른 다음 n을 누르는 것을 의미합니다. ctrl+alt+n, cmd+k, alt+1 및 기능 키 코드 (function-key chords)는 터미널 모드 (terminal-mode)의 직접적인 단축키이며 프리픽스가 필요하지 않습니다. n과 같이 일반적인 출력 가능한 키를 직접 사용하면 일반적인 타이핑을 가로채게 되므로, 의도적으로 수정자 (modifier)가 포함된 직접 바인딩을 원하는 경우가 아니라면 prefix+n을 사용하세요.

에이전트 인식 (Agent awareness). 사이드바에는 차단됨 (blocked), 작업 중 (working), 완료됨 (done), 유휴 상태 (idle)가 표시됩니다. 감지는 기본적으로 프로세스 이름 (process names)과 터미널 출력 (terminal output)을 통해 작동합니다. 공식 통합 기능을 사용하면 상태 보고 (state reporting)와 네이티브 에이전트 세션 복구 (native agent session restore)가 더 안정적으로 이루어지지만, Herdr는 이러한 기능 없이도 터미널 멀티플렉서 (terminal multiplexer)로서 작동합니다.

Herdr는 새 버전이 사용 가능할 때 알림을 보냅니다. 수동으로 실행하려면:

herdr update

herdr update는 Herdr 자체 설치 프로그램에 의해 관리되는 설치에 사용됩니다. Homebrew 및 Nix 설치는 brew upgrade herdr 또는 사용자의 Nix 워크플로 (workflow)를 통해 업데이트합니다. 전체 업데이트, 재시작, 복구 및 핸드오프 매트릭스 (handoff matrix)에 대해서는 설치 문서와 세션 상태 문서를 참조하세요.

	tmux	gui managers	herdr
지속성 세션 (persistent sessions)	✓	—	✓
...

tmux는 지속성 (persistence)과 창 분할 (panes) 기능을 제공하지만, 에이전트 (agents)가 존재하기 전에 만들어졌습니다. GUI 매니저 (gui managers)들은 에이전트 상태를 보여주지만, 터미널을 벗어나 그들이 제공하는 래핑된 뷰 (wrapped view)를 사용하게 만듭니다. herdr는 사용자의 방해를 받지 않으면서 지속성과 인지 능력 (awareness)을 하나의 도구로 결합한 솔루션입니다.

herdr는 일반적인 SSH를 통해 작동합니다. 원격 호스트 (remote host)에서 실행하고, 분리 (detach)한 뒤 나중에 다시 연결 (reattach)하세요:

ssh you@yourserver
herdr

먼저 셸 (shell)을 열지 않고도 로컬 터미널에서 바로 연결 (attach)할 수도 있습니다:

herdr --remote workbox
herdr --remote ssh://you@yourserver:2222

직접 연결 (Direct attach)은 현재 터미널을 서버가 소유한 하나의 터미널에 연결합니다:

herdr agent attach <target>
herdr terminal attach <terminal_id>

원격 키 바인딩 (remote keybinding), 이름이 지정된 세션 (named-session), 그리고 핸드오프 (handoff)에 대한 자세한 내용은 지속성 (persistence) 및 원격 (remote) 문서를 참조하세요.

사이드바 (sidebar)는 어떤 에이전트가 차단 (blocked), 작업 중 (working), 또는 완료 (done)되었는지 보여줍니다. 워크스페이스 (workspaces)는 가장 긴급한 상태로 요약되어 전체 목록을 한눈에 훑어볼 수 있습니다.

상태 (states):

• 🔴 blocked— 에이전트가 입력이나 승인을 필요로 함
• 🟡 working— 에이전트가 활발히 실행 중
• 🔵 done— 작업이 완료되었으나 아직 확인하지 않음
• 🟢 idle— 완료되었고 확인됨

감지는 포그라운드 프로세스 (foreground process)와 터미널 출력을 읽음으로써 작동합니다. 설정이 필요 없으며 (zero config), 후크 (hooks)도 필요하지 않습니다. 후크를 노출하는 에이전트의 경우, 소켓 API (socket api) 통합을 통해 더욱 견고한 상태 보고를 제공합니다.

GUI 창도 아니고, 웹 대시보드 (web dashboard)도 아니며, Electron 기반도 아닙니다. herdr는 여러분이 이미 사용 중인 터미널 내부에서 실행됩니다. 단일 Rust 바이너리 (single rust binary)로 구성되어 의존성 (dependencies)이 없습니다. tmux 내부에서도 작동합니다.

워크스페이스 (workspaces)— git 리포지토리 (git repos) 또는 폴더 이름을 중심으로 구성되며, 각각 고유한 탭 (tabs)과 창 분할 (panes)을 가집니다.
탭 (tabs)— 소켓 API (socket api)와 CLI에서 일급 객체 (first-class)로 취급됩니다.
복사 용이성 (copy-friendly)— 창 분할 텍스트를 드래그하여 선택하거나, 토큰 (tokens)을 더블 클릭하거나, prefix+[를 사용하여 키보드 복사 모드 (keyboard copy mode)를 사용할 수 있습니다.

,, h/j/k/l, {/}, v, 그리고 y

알림 (notifications)— 백그라운드 이벤트에 대한 소리 및 토스트(toasts) 알림; 탭 인식 기반의 억제 기능
18개의 내장 테마 (18 built-in themes)— catppuccin, terminal, tokyo night, gruvbox, one, solarized, kanagawa, rosé pine, vesper, 그리고 주요 팔레트에 대한 라이트 변형(light variants)
세션 지속성 (session persistence)— 클라이언트 분리(detach) 시에도 창(pane) 프로세스가 유지됨; 전체 재시작 후 세션이 창을 복구하며, 선택 사항으로 최근 화면 기록(recent screen history)을 제공

로컬 Unix 소켓을 통해 에이전트(agents)가 워크스페이스(workspaces)를 생성하고, 창(panes)을 분할하며, 헬퍼(helpers)를 실행하고, 출력을 읽고, 상태 변화를 기다릴 수 있습니다. 소켓 API 문서와 SKILL.md로 시작하세요.

자동 감지는 별도의 설정 없이 즉시 작동합니다. 프로세스 이름 매칭과 터미널 출력 휴리스틱(heuristics)을 사용합니다.

에이전트 (agent)	유휴/완료 (idle / done)	작업 중 (working)	차단됨 (blocked)
pi	✓	✓	부분적 (partial)
...
감지되었으나 완전히 테스트되지 않음: gemini cli, cline.

내장 목록에 없는 에이전트의 경우에도, herdr는 워크스페이스, 창(panes), 타일링(tiling) 기능을 갖춘 터미널 멀티플렉서(terminal multiplexer)로서 여전히 작동합니다. 커스텀 통합(custom integrations)을 통해 소켓 API(socket api)로 에이전트 레이블을 보고할 수 있습니다. 소켓 API 문서를 참조하세요.

내장된 pi, omp, claude code, codex, opencode, hermes, 그리고 qodercli 통합 기능은 소켓 API를 통해 herdr로 시맨틱 상태(semantic state)를 전달합니다. 설치 방법은 다음과 같습니다:

herdr integration install pi
herdr integration install omp
herdr integration install claude
...

설정 세부 사항은 통합(integrations) 문서를 참조하세요.

ctrl+b를 눌러

접두사 모드(prefix mode)로 진입합니다. 기본 동작은 접두사 우선 방식이며 tmux와 유사합니다:

키 (key)	동작 (action)
prefix+c	새 탭 (new tab)
prefix+n / prefix+p	다음 / 이전 탭 (next / previous tab)
prefix+1..9	탭 전환 (switch tab)
prefix+w	워크스페이스 탐색 (workspace navigation)
prefix+g	세션 탐색기 (session navigator)
prefix+shift+n	새 워크스페이스 (new workspace)
prefix+shift+g	새 워크트리 (new worktree)
prefix+shift+w	워크스페이스 이름 변경 (rename workspace)
prefix+shift+d	워크스페이스 닫기 (close workspace)
prefix+h/j/k/l	창 포커스 (focus pane)
prefix+v / prefix+minus	창 분할 (split pane)
prefix+x	창 닫기 (close pane)
prefix+b	사이드바 토글 (toggle sidebar)
prefix+z	창 확대 (zoom pane)
prefix+r	크기 조정 모드 (resize mode)
prefix+q	분리 (detach)

전체 과정에서 마우스 사용이 지원됩니다. 크기 조정 모드(Resize mode)는 h / l을 사용합니다.

너비(width) 조절은 j / k를 사용하고,

높이(height) 조절은 l / h를 사용하며,

esc를 눌러 종료합니다. 전체 구문(syntax), 선택적 동작(optional actions), 인덱스 바인딩(indexed bindings), 그리고 사용자 정의 명령 바인딩(custom command bindings)에 대한 정보는 설정 문서(configuration docs)에 있습니다.

설정 파일: ~/.config/herdr/config.toml

herdr --default-config # 전체 기본 설정 출력

앱 내 설정(In-app settings)에서는 테마(theme), 사운드(sound), 토스트(toast) 기본 설정을 다룹니다. Herdr는 ~/.config/herdr/ 아래에 로그를 기록합니다.

지속 세션 모드(persistent session mode)에서는 보통 herdr-client.log와 herdr-server.log 파일이 유용합니다. 전체 설정 및 로깅(logging) 상세 정보는 설정 문서(configuration docs)에 있습니다.

• 퀵 스타트 (quick start) — 첫 세션, 창(panes), 복사(copy), 그리고 이름이 지정된 세션(named sessions)
• 설치 (install) — 설치, 업데이트, Homebrew, 그리고 Nix
• 세션 상태 (session state) — 분리 (detach), 재시작 복구 (restart restore), 에이전트 복구 (agent restore), 그리고 라이브 핸드오프 (live handoff)
• 설정 (configuration) — 키 바인딩 (keybindings), 테마 (themes), 알림 (notifications), 환경 변수 (environment variables)
• 통합 (integrations) — pi, omp, claude code, codex, opencode, hermes, qodercli 통합
  SKILL.md — 재사용 가능한 에이전트 기술 (reusable agent skill) — 소켓 API (socket api) — 소켓 프로토콜 (socket protocol) 및 CLI 레퍼런스 (cli reference)

만약 당신이 이 저장소를 돕는 AI 에이전트라면, 변경 사항을 만들기 전에 AGENTS.md를 읽고, 이슈(issue)나 PR(Pull Request)을 생성하기 전에 CONTRIBUTING.md를 읽으십시오.

git clone https://github.com/ogulcancelik/herdr
cd herdr
cargo build --release
...

Herdr는 이중 라이선스(dual-licensed)를 적용합니다:

• 오픈 소스 (Open source): GNU Affero General Public License v3.0 이상 (AGPL-3.0-or-later).
• 상용 (Commercial): AGPL을 준수할 수 없는 조직을 위해 상용 라이선스를 사용할 수 있습니다.

연락처: hey@herdr.dev