문서 보기이전 판역링크맨 위로 이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요. {{tag>[cli terminal multiplexer ai agent herdr rust]}} ====== herdr ====== AI coding agent의 terminal을 workspace, tab, pane 단위로 구성하고 session을 지속시키는 terminal multiplexer. ===== Summary ===== * ''herdr''를 인자 없이 실행하면 기본 persistent session을 시작하거나 기존 session에 attach한다. * 실제 agent terminal을 pane에 유지하면서 Claude Code, Codex, OpenCode 등 여러 coding agent의 상태를 한 화면에서 확인할 수 있다. * CLI와 local socket API를 이용해 workspace, Git worktree, tab, pane, agent, integration을 script에서 제어할 수 있다. * 대부분의 제어 명령은 실행 중인 Herdr server와 통신하므로 먼저 session을 시작해야 한다. ===== Installation ===== <note important> 원격 설치 script는 실행 전에 공식 ''herdr.dev'' URL인지 확인한다. Windows native 지원은 2026-07-27 기준 preview beta이며 stable channel을 제공하지 않는다. </note> <code bash> # Linux / macOS: 공식 installer curl -fsSL https://herdr.dev/install.sh | sh # macOS / Linuxbrew brew install herdr # mise mise use -g herdr # 설치 확인 herdr --version </code> <code powershell> # Windows preview beta powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" # 설치 확인 herdr --version </code> * Debian/Ubuntu와 RHEL/Fedora용 공식 APT/DNF repository 또는 package는 현재 안내되지 않는다. 공식 Linux installer나 release binary를 사용한다. * Windows는 공식 ''winget'' package가 아니라 preview installer를 제공한다. * Nix 사용자는 release tag를 지정해 ''nix profile install github:ogulcancelik/herdr/v0.x.y'' 형태로 설치할 수 있다. * 직접 installer로 설치한 경우 ''herdr update'', Homebrew/mise/Nix 설치는 각 package manager의 update 명령을 사용한다. ===== Usage ===== <code bash> herdr [OPTIONS] herdr --session NAME [OPTIONS] herdr --remote SSH_TARGET [--session NAME] herdr COMMAND [SUBCOMMAND] [OPTIONS] [ARGS...] </code> * ''<color #c3c3c3>**herdr**</color> <color #22b14c>[OPTIONS]</color>'' * ''<color #c3c3c3>**herdr**</color> <color #22b14c>--session</color> <color #7092be>NAME</color>'' * ''<color #c3c3c3>**herdr**</color> <color #22b14c>--remote</color> <color #7092be>SSH_TARGET</color>'' * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>workspace</color> <color #ff7f27>create</color> <color #22b14c>[OPTIONS]</color>'' * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane</color> <color #ff7f27>read</color> <color #7092be>PANE_ID</color> <color #22b14c>[OPTIONS]</color>'' ===== Options ===== * ''<color #22b14c>**--session**</color> <color #7092be>NAME</color>'': named persistent session을 사용하거나 생성한다. * ''<color #22b14c>**--remote**</color> <color #7092be>TARGET</color>'': SSH를 통해 원격 Herdr server에 attach한다. * ''<color #22b14c>**--remote-keybindings**</color> <color #7092be>local|server</color>'': remote attach에서 local 또는 server keybinding을 사용한다. * ''<color #22b14c>**--handoff**</color>'': 지원되는 update 또는 remote attach에서 experimental live handoff를 요청한다. * ''<color #22b14c>**--no-session**</color>'': server/client를 쓰지 않는 단일 process escape hatch로 실행한다. * ''<color #22b14c>**--default-config**</color>'': 전체 기본 TOML 설정을 stdout에 출력한다. * ''<color #22b14c>**--version**</color>'', ''<color #22b14c>**-V**</color>'': version을 출력한다. ===== Commands ===== ==== Launch and Status ==== * ''<color #c3c3c3>**herdr**</color>'': 기본 persistent session 시작 또는 attach * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>status</color> <color #7092be>[server|client]</color>'': local client와 server 상태 확인 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>server</color>'': headless server 실행 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>server stop</color>'': 실행 중인 server 중지 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>server reload-config</color>'': 실행 중인 server에서 ''config.toml'' 다시 읽기 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>api schema</color> <color #22b14c>[--json|--output</color> <color #7092be>PATH</color><color #22b14c>]</color>'': binary에 포함된 socket API schema 확인 ==== Session and Workspace ==== * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>session list</color> <color #22b14c>[--json]</color>'': persistent session 목록 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>session attach</color> <color #7092be>NAME</color>'': named session에 attach * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>session stop</color> <color #7092be>NAME</color> <color #22b14c>[--json]</color>'': named session 중지 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>workspace list</color>'': workspace 목록 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>workspace create</color> <color #22b14c>[--cwd</color> <color #7092be>PATH</color><color #22b14c>] [--label</color> <color #7092be>TEXT</color><color #22b14c>] [--env</color> <color #7092be>KEY=VALUE</color><color #22b14c>] [--focus|--no-focus]</color>'': workspace 생성 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>workspace focus</color> <color #7092be>WORKSPACE_ID</color>'': workspace focus 이동 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>workspace rename</color> <color #7092be>WORKSPACE_ID LABEL</color>'': 표시 이름 변경 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>workspace close</color> <color #7092be>WORKSPACE_ID</color>'': Herdr workspace 상태 닫기 <note warning> ''<color #c3c3c3>**herdr**</color> <color #ff7f27>session delete</color> <color #7092be>NAME</color>''은 저장된 session 상태를 삭제한다. 필요한 session인지 ''session list''로 확인한 뒤 실행한다. </note> ==== Git Worktree ==== * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>worktree list</color> <color #22b14c>[--workspace</color> <color #7092be>ID</color><color #22b14c>|--cwd</color> <color #7092be>PATH</color><color #22b14c>] [--json]</color>'': workspace와 연결된 worktree 목록 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>worktree create</color> <color #22b14c>[--workspace</color> <color #7092be>ID</color><color #22b14c>|--cwd</color> <color #7092be>PATH</color><color #22b14c>] [--branch</color> <color #7092be>NAME</color><color #22b14c>] [--base</color> <color #7092be>REF</color><color #22b14c>] [--path</color> <color #7092be>PATH</color><color #22b14c>] [--label</color> <color #7092be>TEXT</color><color #22b14c>] [--focus|--no-focus] [--json]</color>'': Git worktree를 만들고 workspace로 연다. * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>worktree open</color> <color #22b14c>(--path</color> <color #7092be>PATH</color><color #22b14c>|--branch</color> <color #7092be>NAME</color><color #22b14c>) [OPTIONS]</color>'': 기존 Git worktree를 workspace로 연다. * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>worktree remove</color> <color #22b14c>--workspace</color> <color #7092be>ID</color> <color #22b14c>[--force] [--json]</color>'': checkout을 ''git worktree remove''로 제거한다. <note warning> ''workspace close''는 Herdr 상태만 닫지만 ''worktree remove''는 실제 checkout directory를 제거한다. dirty checkout에서 ''--force''를 사용하면 작업 파일을 잃을 수 있다. </note> ==== Tab, Pane, and Agent ==== * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>tab list</color> <color #22b14c>[--workspace</color> <color #7092be>ID</color><color #22b14c>]</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>tab create</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>tab focus</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>tab rename</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>tab close</color>'': tab lifecycle 관리 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane list</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane split</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane focus</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane close</color>'': pane layout과 lifecycle 관리 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane read</color> <color #7092be>PANE_ID</color> <color #22b14c>--source</color> <color #7092be>visible|recent|recent-unwrapped|detection</color> <color #22b14c>[--lines</color> <color #7092be>N</color><color #22b14c>] [--ansi]</color>'': terminal output 읽기 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane send-text</color> <color #7092be>PANE_ID TEXT</color>'': text 입력 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane send-keys</color> <color #7092be>PANE_ID KEY [KEY...]</color>'': key 또는 key chord 입력 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>pane run</color> <color #7092be>PANE_ID COMMAND</color>'': pane에서 shell command 실행 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>agent list</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>agent read</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>agent wait</color>'', ''<color #c3c3c3>**herdr**</color> <color #ff7f27>agent explain</color>'': 감지된 agent, terminal output, 상태 대기와 감지 진단 ==== Integration, Plugin, and Completion ==== * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>integration install</color> <color #7092be>codex</color>'': Codex integration 설치 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>integration status</color> <color #22b14c>[--outdated-only]</color>'': integration 상태 확인 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>plugin install</color> <color #7092be>OWNER/REPO[/SUBDIR]</color> <color #22b14c>[--ref</color> <color #7092be>REF</color><color #22b14c>] [--yes]</color>'': GitHub plugin 설치 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>plugin list</color> <color #22b14c>[--plugin</color> <color #7092be>ID</color><color #22b14c>] [--json]</color>'': plugin 목록 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>plugin link</color> <color #7092be>PATH</color>'': local plugin 개발 directory 연결 * ''<color #c3c3c3>**herdr**</color> <color #ff7f27>completion</color> <color #7092be>SHELL</color>'': ''bash'', ''zsh'', ''fish'', ''powershell'', ''elvish'' completion 출력 <note important> Plugin은 local executable workflow를 실행할 수 있다. source와 manifest를 검토한 뒤 설치하고, automation에서만 ''--yes''를 사용한다. </note> ===== Examples ===== ==== Start and Detach ==== <code bash> # 기본 session 시작 또는 재접속 herdr # 별도 named session herdr --session work # 상태 확인 herdr status herdr session list --json </code> * 기본 prefix는 <kbd>Ctrl</kbd>+<kbd>b</kbd>다. * 기본 keybinding에서 ''prefix+d''로 detach하고, ''prefix+c''로 tab을 만들며, ''prefix+v'' 또는 ''prefix+-''로 pane을 분할한다. * active keybinding은 ''prefix+?'' help panel에서 확인한다. ==== Workspace Automation ==== <code bash> # 현재 project를 focus를 빼앗지 않고 workspace로 생성 herdr workspace create --cwd "$PWD" --label api --no-focus # API 응답을 script에서 쓰기 위한 JSON 조회 herdr session list --json # 최근 pane output 120줄 읽기 herdr pane read 1-1 --source recent-unwrapped --lines 120 </code> ==== Remote Attach ==== <code bash> # ~/.ssh/config의 host alias 사용 herdr --remote workbox # named remote session에 attach herdr --remote workbox --session work # server 측 keybinding 사용 herdr --remote workbox --remote-keybindings server </code> ==== Shell Completion ==== <code bash> # 현재 zsh session에 임시 적용 source <(herdr completion zsh) # persistent zsh completion file 생성 mkdir -p ~/.zfunc herdr completion zsh > ~/.zfunc/_herdr </code> ===== Configuration ===== * Linux/macOS: ''~/.config/herdr/config.toml'' * Windows: ''%APPDATA%\herdr\config.toml'' * ''HERDR_CONFIG_PATH'' 환경 변수로 config file 경로를 override할 수 있다. * 기본 설정 출력, TOML key, keybinding, theme, notification, validation은 [[herdr:config:ko|Herdr configuration]]을 참고한다. ===== Troubleshooting ===== * ''herdr: command not found''이면 terminal을 다시 열고 installer가 추가한 directory가 ''PATH''에 포함되었는지 확인한다. * server 연결 문제가 있으면 ''herdr status server''와 ''~/.config/herdr/herdr-server.log''를 확인한다. * 잘못된 config value는 safe default로 fallback되고 startup warning이 표시된다. ''herdr --default-config''와 비교한 뒤 ''herdr server reload-config''를 실행한다. * remote attach가 실패하면 먼저 ''ssh TARGET''이 정상 동작하는지 확인하고 ''~/.ssh/config''의 host, key, jump host 설정을 점검한다. * pane output에 ANSI escape가 필요하면 ''--ansi'' 또는 ''--format ansi''를 사용한다. 기본 출력은 ANSI를 제거한다. ===== Compatibility ===== * stable binary는 Linux와 macOS를 지원한다. * Windows native binary와 installer는 preview-only beta다. * remote attach에는 SSH client와 원격 host의 Herdr 설치가 필요하다. * Homebrew, mise, Nix installation은 Herdr 자체 update channel이 아니라 해당 package manager로 update한다. ===== Help ===== ++++ herdr --help | <code text> herdr — terminal workspace manager for AI coding agents Usage: herdr [options] herdr --session <name> [options] herdr --remote <ssh-target> [--session <name>] herdr session attach <name> herdr completion zsh herdr update [--handoff] herdr channel set <stable|preview> herdr server stop herdr server reload-config herdr api <subcommand> ... herdr completion <shell> herdr config <subcommand> ... herdr channel <subcommand> ... herdr workspace <subcommand> ... herdr worktree <subcommand> ... herdr tab <subcommand> ... herdr notification <subcommand> ... herdr agent <subcommand> ... herdr pane <subcommand> ... herdr session <subcommand> ... herdr integration <subcommand> ... Common commands: herdr Launch or attach to the persistent session herdr status [server|client] Show local client and running server status herdr update Download and install the latest version herdr completion zsh Generate shell completions for zsh herdr server stop Stop the running server via the API socket herdr channel set <stable|preview> Choose the stable or preview update channel herdr server reload-config Reload config.toml in the running server herdr config reset-keys Back up config.toml and remove custom keybindings herdr channel <subcommand> Manage the stable or preview update channel herdr api <subcommand> Inspect socket API metadata and live runtime state herdr workspace <subcommand> Workspace helpers over the socket API herdr worktree <subcommand> Git worktree helpers over the socket API herdr tab <subcommand> Tab helpers over the socket API herdr notification <subcommand> Notification helpers over the socket API herdr agent <subcommand> Agent/terminal helpers over the socket API herdr pane <subcommand> Pane control helpers over the socket API herdr session <subcommand> Manage named persistent sessions herdr integration <subcommand> Manage built-in agent integrations Advanced commands: herdr server Run as headless server Options: --no-session Run monolithically (no server/client, escape hatch) --session <name> Use or create a named persistent session --remote <target> Attach through SSH to a remote Herdr server --remote-keybindings <local|server> Keybindings for --remote app attach (default: local) --handoff Opt into live handoff for update or remote attach --default-config Print default configuration and exit --version, -V Print version and exit --help, -h Show this help Config: ~/.config/herdr/config.toml Logs: ~/.config/herdr/herdr.log (plus herdr-client.log, herdr-server.log) Env: HERDR_CONFIG_PATH overrides config file path Home: https://herdr.dev </code> ++++ ===== See Also ===== * [[herdr:config:ko|Herdr configuration]] * [[claude:ko|Claude Code]] * [[codex:ko|Codex CLI]] * [[https://herdr.dev/docs/install/|Install Herdr]] * [[https://herdr.dev/docs/cli-reference/|Herdr CLI reference]] * [[https://github.com/ogulcancelik/herdr|ogulcancelik/herdr]] ===== History ===== * codex:: 2026-07-27 Standardized command entries with executable, subcommand, option, and argument colors. * codex:: 2026-07-27 Added installation, session, workspace, worktree, pane, integration, remote attach, safety, and live ''herdr 0.7.5'' help guidance. {{indexmenu>.#1|js}} /home/u613600155/domains/cli.zerotymer.net/public_html/data/pages/herdr/ko.txt 마지막으로 수정됨: 2026/07/27 00:02저자 127.0.0.1