Herdr

Linux / macOS installer

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

Windows

curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd

mise

mise use -g herdr

Nix

nix profile install github:herdrdev/herdr/v0.x.y

pi claude codex gemini cursor devin agy cline omp mastracode opencode copilot kimi kiro droid amp grok hermes kilo qodercli qwen maki

Names must match [a-z][a-z0-9_-]{0,31} and be unique among live agents.

cd ~/project
herdr                         # launch/attach default session
# Run your shell, editor, agent, dev server normally.
# Detach in the UI: Ctrl+B, then Q
herdr                         # reattach later
herdr status                  # inspect server/client state
herdr server stop             # only when you truly want to end it

herdr --session work
herdr --session personal

herdr session list
herdr session attach work
herdr session stop work
herdr session delete work

Use workspaces inside one session for ordinary project separation. Named sessions are useful when you need independent servers or lifecycles.

herdr worktree create \
  --cwd ~/project \
  --branch feat/api-cache \
  --base main \
  --label api-cache \
  --focus

herdr worktree list --cwd ~/project
herdr worktree open --cwd ~/project --branch feat/api-cache

# Close Herdr state only:
herdr workspace close <workspace_id>

# Remove checkout; branch is never deleted:
herdr worktree remove --workspace <workspace_id>

If Git refuses to remove a dirty checkout, Herdr requires --force. Review uncommitted work first.

herdr pane run w1:p3 "npm run dev"
herdr pane wait-output w1:p3 \
  --regex "ready|listening|Local:" \
  --source recent-unwrapped \
  --timeout 120000

herdr pane read w1:p3 --source recent-unwrapped --lines 80

Use pane output waits for servers, tests, and ordinary commands. Use agent wait for coding agents.

split=$(herdr pane split --current --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')

herdr agent start reviewer --kind codex --pane "$review_pane"
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 120

• herdr — Launch or attach to the default session.
• herdr --session work — Launch or attach to a named session.
• herdr --remote workbox — Attach through SSH using local keybindings.
• herdr --remote workbox --remote-keybindings server — Use the remote server’s keybindings.
• herdr --remote workbox --handoff — Opt into supported live server handoff.
• herdr --no-session — Single-process escape hatch without persistence.
• herdr status [server|client] — Inspect overall, server, or client state.
• herdr --default-config — Print the full commented default config.
• herdr update [--handoff] — Update direct installs; package-manager installs update there.
• herdr channel show|set stable|set preview — Inspect or change direct-install update channel.
• herdr completion zsh|bash|fish|powershell|elvish — Print a shell completion script. completions is an alias.
• herdr api schema [--json|--output PATH] — Inspect or export the socket protocol schema.
• herdr --version — Print installed version.

herdr server
herdr server stop
herdr server reload-config
herdr server agent-manifests [--json]
herdr server update-agent-manifests [--json]
herdr server reload-agent-manifests

herdr notification show <title> \
  [--body TEXT] \
  [--position top-left|top-right|bottom-left|bottom-right] \
  [--sound none|done|request]

herdr session list [--json]
herdr session attach <name>
herdr session stop <name> [--json]
herdr session delete <name> [--json]

herdr workspace list
herdr workspace create [--cwd PATH] [--label TEXT] \
  [--env KEY=VALUE] [--focus|--no-focus]
herdr workspace get <workspace_id>
herdr workspace focus <workspace_id>
herdr workspace rename <workspace_id> <label>
herdr workspace report-metadata <workspace_id> --source ID \
  [--token NAME=VALUE] [--clear-token NAME] \
  [--seq N] [--ttl-ms N]
herdr workspace close <workspace_id>

Creation returns workspace, first tab, and root pane IDs in JSON. Creation leaves focus unchanged unless --focus is supplied.

herdr worktree list [--workspace ID | --cwd PATH]
herdr worktree create [--workspace ID | --cwd PATH] \
  [--branch NAME] [--base REF] [--path PATH] [--label TEXT] \
  [--focus|--no-focus]
herdr worktree open [--workspace ID | --cwd PATH] \
  (--path PATH | --branch NAME) [--label TEXT] [--focus|--no-focus]
herdr worktree remove --workspace ID [--force]

workspace close only closes Herdr state. worktree remove deletes the checkout through Git but never deletes the branch.

herdr tab list [--workspace <workspace_id>]
herdr tab create [--workspace <workspace_id>] [--cwd PATH] \
  [--label TEXT] [--env KEY=VALUE] [--focus|--no-focus]
herdr tab get <tab_id>
herdr tab focus <tab_id>
herdr tab rename <tab_id> <label>
herdr tab close <tab_id>

Closing a workspace’s last tab also closes that workspace.

herdr pane list [--workspace <workspace_id>]
herdr pane current [--pane ID|--current]
herdr pane get <pane_id>
herdr pane layout [--pane ID|--current]
herdr pane process-info [--pane ID|--current]
herdr pane neighbor --direction left|right|up|down [--pane ID|--current]
herdr pane edges [--pane ID|--current]
herdr pane focus --direction left|right|up|down [--pane ID|--current]
herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
herdr pane rename <pane_id> <label>|--clear
herdr pane input [<pane_id>|--pane ID|--current] --right-click herdr|pane
herdr pane split [<pane_id>|--pane ID|--current] \
  --direction right|down [--ratio FLOAT] [--cwd PATH] \
  [--env KEY=VALUE] [--right-click herdr|pane] [--focus|--no-focus]
herdr pane swap --direction left|right|up|down [--pane ID|--current]
herdr pane swap --source-pane ID --target-pane ID
herdr pane move <pane_id> --tab <tab_id> --split right|down \
  [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
herdr pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus]
herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus]
herdr pane close <pane_id>

Inside Herdr, --current resolves from HERDR_PANE_ID. An omitted split target uses the UI-focused pane.

herdr pane read <pane_id> \
  [--source visible|recent|recent-unwrapped|detection] \
  [--lines N] [--format text|ansi] [--ansi] [--raw]

herdr pane send-text <pane_id> <text>
herdr pane send-keys <pane_id> <key> [key ...]
herdr pane run <pane_id> <command>

herdr pane wait-output <pane_id> \
  (--match <text> | --regex <pattern>) \
  [--source visible|recent|recent-unwrapped] \
  [--lines N] [--timeout MS] [--raw]

pane run submits a command plus Enter atomically and is preferred over separate text/key sends.

herdr agent list
herdr agent get <target>
herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] \
  [--lines N] [--format text|ansi] [--ansi]
herdr agent send-keys <target> <key> [key ...]
herdr agent prompt <target> <text> \
  [--wait] [--until STATUS]... [--timeout MS]
herdr agent rename <target> <name>|--clear
herdr agent focus <target>
herdr agent wait <target> [--until STATUS]... [--timeout MS]
herdr agent attach <target> [--takeover]
herdr agent start <name> --kind KIND --pane ID \
  [--timeout MS] [-- <agent-args...>]
herdr agent explain <target> [--json|--verbose]
herdr agent explain --file PATH --agent LABEL [--json|--verbose]

A target is a unique live agent name or the pane ID hosting it. Bare agent-kind labels are not targets.

herdr terminal attach <terminal_id> [--takeover]
herdr terminal session control <target> [--takeover] [--cols N] [--rows N]
herdr terminal session observe <target> [--cols N] [--rows N]
herdr terminal title set <title>
herdr terminal title clear

Detach from direct attach with ctrl+b q. Send a literal ctrl+b with ctrl+b ctrl+b. Observe streams are read-only; one controller owns writable control at a time.

herdr integration install <agent>
herdr integration uninstall <agent>
herdr integration status [--outdated-only]

Install an integration for improved lifecycle accuracy. Supported install targets include pi, omp, claude, codex, copilot, devin, droid, kimi, opencode, kilo, hermes, qodercli, qwen, cursor, mastracode, and grok.

onboarding = false

[terminal]
shell_mode = "auto"
new_cwd = "follow"

[worktrees]
directory = "~/.herdr/worktrees"

[remote]
manage_ssh_config = true

[keys]
prefix = "ctrl+b"
help = "prefix+?"
new_tab = "prefix+c"
next_tab = "prefix+n"
previous_tab = "prefix+p"
focus_pane_left = ["prefix+h", "ctrl+alt+h"]
focus_pane_down = ["prefix+j", "ctrl+alt+j"]
focus_pane_up = ["prefix+k", "ctrl+alt+k"]
focus_pane_right = ["prefix+l", "ctrl+alt+l"]
split_vertical = ["prefix+v", "ctrl+alt+d"]
split_horizontal = ["prefix+minus", "ctrl+alt+shift+d"]
zoom = ["prefix+z", "ctrl+alt+z"]

Direct ctrl+alt chords are broadly terminal-safe, but check operating-system and terminal bindings. Keep the prefix alternatives until the direct map is proven.

# Temporary zsh completion
source <(herdr completion zsh)

# Persistent zsh completion
mkdir -p ~/.zfunc
herdr completion zsh > ~/.zfunc/_herdr

# Add before compinit in ~/.zshrc:
fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

herdr config reset-keys
herdr server reload-config

Herdr backs up config.toml, removes custom key tables, and returns to built-in v2 defaults.

This guide reflects the latest stable release (v0.8.2). Notable additions: ui.window_title keeps the outer terminal window title in sync with the active workspace and host; optional keys.move_tab_previous / keys.move_tab_next reorder the active tab; and the desktop tab bar accepts configurable right-aligned status entries. Qwen Code detection was also added. Exact syntax lives in herdr --default-config.

Run herdr again. Closing the client normally leaves the background server alive. If the session is absent, check herdr status server and herdr session list. --no-session is intentionally non-persistent.

Prefix bindings are sequential: Ctrl+B, release, then the action key. Open prefix+? to inspect the active map. If a direct chord fails, the OS or outer terminal may consume it before Herdr sees it.

herdr integration status --outdated-only
herdr server agent-manifests --json
herdr server update-agent-manifests --json
herdr agent explain <target> --verbose

Install the official integration for that agent when available. Use agent explain to inspect the rule and evidence that produced the state.

herdr server reload-config

Most UI settings reload live; startup-only settings require a session restart. Invalid values fall back safely and produce a startup warning.

Use explicit IDs in scripts. Inside a Herdr-managed pane, --current resolves through HERDR_PANE_ID. Omitting a target can use the UI-focused pane, which is convenient interactively but fragile in automation.

Git found modified or untracked files. Inspect them before using herdr worktree remove --workspace ID --force. Removal deletes the checkout, never the branch.

If you SSH first and run Herdr remotely, the process cannot access your local desktop clipboard. Use herdr --remote host so a local thin client can bridge image paste.

herdr update only applies to direct installs made with the shell installer. Homebrew, mise, and Nix installs update through their own package manager. Check the channel with herdr channel show and the installed build with herdr --version.

Pass the literal name default: herdr session stop default or herdr session delete default. Bare herdr attaches to the default session, but the stop and delete verbs need an explicit name.

--wait watches lifecycle state, not a unique turn. If the agent was already working, that active work can satisfy the wait. Use exact --until states plus a --timeout, then confirm the result with agent read rather than trusting the wait alone.