[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

원격 설치 script는 실행 전에 공식 herdr.dev URL인지 확인한다. Windows native 지원은 2026-07-27 기준 preview beta이며 stable channel을 제공하지 않는다.

# Linux / macOS: 공식 installer
curl -fsSL https://herdr.dev/install.sh | sh
 
# macOS / Linuxbrew
brew install herdr
 
# mise
mise use -g herdr
 
# 설치 확인
herdr --version

# Windows preview beta
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
 
# 설치 확인
herdr --version

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

herdr [OPTIONS]
herdr --session NAME [OPTIONS]
herdr --remote SSH_TARGET [--session NAME]
herdr COMMAND [SUBCOMMAND] [OPTIONS] [ARGS...]

herdr [OPTIONS]
herdr –session NAME
herdr –remote SSH_TARGET
herdr workspace create [OPTIONS]
herdr pane read PANE_ID [OPTIONS]

Options

–session NAME: named persistent session을 사용하거나 생성한다.
–remote TARGET: SSH를 통해 원격 Herdr server에 attach한다.
–remote-keybindings local|server: remote attach에서 local 또는 server keybinding을 사용한다.
–handoff: 지원되는 update 또는 remote attach에서 experimental live handoff를 요청한다.
–no-session: server/client를 쓰지 않는 단일 process escape hatch로 실행한다.
–default-config: 전체 기본 TOML 설정을 stdout에 출력한다.
–version, -V: version을 출력한다.

Commands

Launch and Status

herdr: 기본 persistent session 시작 또는 attach
herdr status [server|client]: local client와 server 상태 확인
herdr server: headless server 실행
herdr server stop: 실행 중인 server 중지
herdr server reload-config: 실행 중인 server에서 config.toml 다시 읽기
herdr api schema [–json|–output PATH]: binary에 포함된 socket API schema 확인

Session and Workspace

herdr session list [–json]: persistent session 목록
herdr session attach NAME: named session에 attach
herdr session stop NAME [–json]: named session 중지
herdr workspace list: workspace 목록
herdr workspace create [–cwd PATH] [–label TEXT] [–env KEY=VALUE] [–focus|–no-focus]: workspace 생성
herdr workspace focus WORKSPACE_ID: workspace focus 이동
herdr workspace rename WORKSPACE_ID LABEL: 표시 이름 변경
herdr workspace close WORKSPACE_ID: Herdr workspace 상태 닫기

herdr session delete NAME은 저장된 session 상태를 삭제한다. 필요한 session인지 session list로 확인한 뒤 실행한다.

Git Worktree

herdr worktree list [–workspace ID|–cwd PATH] [–json]: workspace와 연결된 worktree 목록
herdr worktree create [–workspace ID|–cwd PATH] [–branch NAME] [–base REF] [–path PATH] [–label TEXT] [–focus|–no-focus] [–json]: Git worktree를 만들고 workspace로 연다.
herdr worktree open (–path PATH|–branch NAME) [OPTIONS]: 기존 Git worktree를 workspace로 연다.
herdr worktree remove –workspace ID [–force] [–json]: checkout을 git worktree remove로 제거한다.

workspace close는 Herdr 상태만 닫지만 worktree remove는 실제 checkout directory를 제거한다. dirty checkout에서 –force를 사용하면 작업 파일을 잃을 수 있다.

Tab, Pane, and Agent

herdr tab list [–workspace ID], herdr tab create, herdr tab focus, herdr tab rename, herdr tab close: tab lifecycle 관리
herdr pane list, herdr pane split, herdr pane focus, herdr pane close: pane layout과 lifecycle 관리
herdr pane read PANE_ID –source visible|recent|recent-unwrapped|detection [–lines N] [–ansi]: terminal output 읽기
herdr pane send-text PANE_ID TEXT: text 입력
herdr pane send-keys PANE_ID KEY [KEY…]: key 또는 key chord 입력
herdr pane run PANE_ID COMMAND: pane에서 shell command 실행
herdr agent list, herdr agent read, herdr agent wait, herdr agent explain: 감지된 agent, terminal output, 상태 대기와 감지 진단

Integration, Plugin, and Completion

herdr integration install codex: Codex integration 설치
herdr integration status [–outdated-only]: integration 상태 확인
herdr plugin install OWNER/REPO[/SUBDIR] [–ref REF] [–yes]: GitHub plugin 설치
herdr plugin list [–plugin ID] [–json]: plugin 목록
herdr plugin link PATH: local plugin 개발 directory 연결
herdr completion SHELL: bash, zsh, fish, powershell, elvish completion 출력

Plugin은 local executable workflow를 실행할 수 있다. source와 manifest를 검토한 뒤 설치하고, automation에서만 –yes를 사용한다.

Examples

Start and Detach

# 기본 session 시작 또는 재접속
herdr
 
# 별도 named session
herdr --session work
 
# 상태 확인
herdr status
herdr session list --json

기본 prefix는 Ctrl+B다.
기본 keybinding에서 prefix+d로 detach하고, prefix+c로 tab을 만들며, prefix+v 또는 prefix+-로 pane을 분할한다.
active keybinding은 prefix+? help panel에서 확인한다.

Workspace Automation

# 현재 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

Remote Attach

# ~/.ssh/config의 host alias 사용
herdr --remote workbox
 
# named remote session에 attach
herdr --remote workbox --session work
 
# server 측 keybinding 사용
herdr --remote workbox --remote-keybindings server

Shell Completion

# 현재 zsh session에 임시 적용
source <(herdr completion zsh)
 
# persistent zsh completion file 생성
mkdir -p ~/.zfunc
herdr completion zsh > ~/.zfunc/_herdr

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 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

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

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.

config
herdr

목차