Herdr

herdr

Purpose

You are driving herdr, a CLI + NDJSON socket for controlling a persistent fleet of terminal panes (and the agents running inside them). Every workspace, tab, and pane is a real, addressable object you can spawn, prompt, read, wait on, and close from the command line — locally, in named sessions, or over SSH. Unlike a plain multiplexer, herdr also tracks semantic agent state (idle · working · blocked · done), so you can block on "the agent finished" instead of scraping screens.

Instructions

Discover commands first (--help)

Before doing anything, run:

herdr --help
herdr <command> --help     # e.g. herdr pane --help, herdr wait --help

herdr evolves fast (validated here against 0.7.1); trust --help over memory. Never guess flags — confirm them.

When you need the full surface at once — every command's flags, the socket API's method families, event types, environment variables, or config keys — read references/command-reference.md instead of running many --help calls. It's the validated lookup table (including all reproduced gotchas); still confirm against --help if the installed version differs from 0.7.1.

Make sure a server is running

The CLI talks to a server over ~/.config/herdr/herdr.sock. Check and start:

herdr status server            # "status: running" or "not running"
herdr server &                 # headless server — no TUI needed to orchestrate

Anyone on the box can drive the socket — you do not need to run inside a herdr pane to orchestrate (no permission mode to raise). Inside a pane, HERDR_ENV=1 plus HERDR_PANE_ID / HERDR_TAB_ID / HERDR_WORKSPACE_ID tell you where you are; use them to avoid touching your own pane.

Understand the hierarchy

Everything nests in one tree. Learn the boxes and the verbs fall out:

• Session → a persistent server (default, or named via --session <name>).
• Workspace → a project-level container. ID: w1.
• Tab → a page of panes inside a workspace. ID: w1:t1.
• Pane → one real PTY (a shell or an agent). ID: w1:p1.

Every command returns JSON on stdout — parse IDs from the result, never guess them. IDs compact as things close; refresh with list before acting.

herdr workspace list                 # all workspaces
herdr tab list --workspace w1        # tabs in a workspace
herdr pane list                      # every pane + its agent_status
herdr agent list                     # only panes with a detected/reported agent

Create the topology

# Workspace: capture workspace_id AND the root pane_id from one call.
herdr workspace create --cwd "$PWD" --label fleet --no-focus
#   → .result.workspace.workspace_id  (w1)
#   → .result.root_pane.pane_id       (w1:p1)

# Splits: each returns the new pane's id.
P2=$(herdr pane split w1:p1 --direction right --no-focus | jq -r .result.pane.pane_id)
P3=$(herdr pane split w1:p1 --direction down  --no-focus | jq -r .result.pane.pane_id)

# Tabs and env injection:
herdr tab create --workspace w1 --label logs --no-focus
herdr pane split w1:p1 --direction right --env OPENROUTER_API_KEY="$OPENROUTER_API_KEY" --no-focus

• Always pass --no-focus when scripting so you don't steal the human's focus.
• Env injection is per-flag (--env KEY=VALUE, repeatable) on workspace create, tab create, pane split, and agent start — there is no --env-file; expand from your own shell (--env KEY="$KEY") and never echo the values.
• Closing the last pane deletes the workspace (verified). Never pane close the sole/root pane of a workspace you want to keep — the workspace goes with it, and a pending agent start --workspace <id> against it fails silently. To swap what's in a workspace, split the NEW pane in FIRST, then close the old one; to reuse the root pane, pane run/agent start --split off it rather than closing it.
• Capture BOTH ids from workspace create — .result.workspace.workspace_id AND .result.root_pane.pane_id — and thread them through; never rely on focus to place a pane.

The control loop

You operate panes the way a person would, but over the CLI:

herdr pane run       w1:p2 "just test"       # type a command AND press Enter
herdr pane send-text w1:p2 "some text"       # type only — does NOT submit
herdr pane send-keys w1:p2 enter             # press a key (esc, tab, ctrl+c, up…)
herdr pane read      w1:p2 --source visible --lines 40    # your eyes
herdr pane close     w1:p2                   # end a pane cleanly

• pane run = text + Enter. send-text types only. For shell commands use run; for driving an interactive TUI agent use send-text then send-keys enter as two steps.
• send-keys accepts real chords (ctrl+c, alt+x, shift+tab) — you can interrupt a running process without killing the pane.
• Read sources: visible (current screen — the reliable default), recent / recent-unwrapped (scrollback; -unwrapped undoes pane-width line wrapping). Scrollback reads can come back empty until output has actually scrolled — if recent returns nothing, fall back to visible.
• Fresh panes buffer input. Text sent before the shell finishes starting is queued, not lost — but reads will look empty for a beat. Give a new pane a moment (or wait output --match '\$|%' --regex) before judging silence.

Wait, don't poll

herdr's killer verbs are blocking waits — prefer them over sleep+read loops:

# Block until a pane prints something (returns the matched line + a read payload):
herdr wait output w1:p3 --match "Server running" --timeout 60000
herdr wait output w1:p3 --match "PASS|FAIL" --regex --timeout 120000

# Block until an agent's semantic state changes (the agent-finished signal):
herdr wait agent-status w1:p2 --status idle --timeout 300000

• Sentinel pitfall (verified): wait output also matches the echoed command line. If you run echo DONE_TOKEN, the wait fires on the typed command, not the output. Split the sentinel in the command — sh -c 'make test && echo DONE_"TOKEN"' — so only real output matches.
• Stale-scrollback pitfall (verified 0.7.1): wait output can also fire on matching text ALREADY in the pane from earlier runs — it is not "new output only." For TUI agents that print the same marker format every turn (e.g. a per-run artifacts: line), a repeated-marker wait false-fires instantly on the previous turn's output. For driving multi-turn TUI sessions, poll the app's state line instead (e.g. read the last footer rows every 10-15s until no working appears for several consecutive polls), or match text unique to the NEW turn.
• wait agent-status needs the pane to have an agent state: launch through an installed integration (herdr integration install claude codex … — one per call) or via herdr agent start, or self-report (below). A bare shell pane stays unknown forever and the wait just times out.
• For fan-in across many panes, run several waits in parallel shell jobs and wait on them, or subscribe to events on the socket (see Socket API).

Semantic agent state — the beyond-tmux feature

Every pane carries agent_status: idle · working · blocked · done · unknown. Integrated agents report it automatically; your own scripts can too:

herdr pane report-agent w1:p4 --source custom:build --agent worker-1 \
  --state working --message "compiling"          # …later: --state idle
herdr agent list                                  # fleet dashboard in one call
herdr agent read worker-1 --source visible --lines 30   # target agents BY NAME
herdr agent send worker-1 "continue"              # literal text (no Enter — send-keys after)

agent <verb> targets accept agent names, terminal ids, or pane ids — name your agents and stop threading pane ids everywhere.

Launching agents

# Named, tracked, declarative — prefer agent start over run "claude":
herdr agent start reviewer --workspace w1 --split right --no-focus -- \
  claude --dangerously-skip-permissions "review this repo"

# Codex unattended:  codex -m gpt-5.5 --dangerously-bypass-approvals-and-sandbox "<task>"
# pi:                pi --model <model> "<task>"

# Claude Code + the user's real Chrome (browser-driving agent):
herdr agent start creds-runner --tab w1:t1 --split down --cwd <repo> --no-focus -- \
  claude --dangerously-skip-permissions --chrome "<task that browses>"

• agent start --split / pane split with no explicit target splits the FOCUSED pane — which may be in another workspace entirely, landing your agent in the wrong place. ALWAYS target explicitly: --tab <ws>:t1 (or --workspace <ws>), or split the captured root_pane.pane_id.

• Always pass --cwd "$PWD" on agent start — it otherwise defaults to ~/Desktop, so a repo-relative brief pointer ("Read prompts/x.md") fails.

• Safe pattern — launch an agent into a FRESH workspace (capture both ids, target explicitly, never close the root pane):

  read WS ROOT < <(herdr workspace create --cwd "$PWD" --label <topic> --no-focus \
    | jq -r '.result | "\(.workspace.workspace_id) \(.root_pane.pane_id)"')
  herdr agent start <name> --tab "${WS}:t1" --split right --cwd "$PWD" --no-focus -- \
    claude --dangerously-skip-permissions --model <model> "Read prompts/<brief>.md and execute end-to-end."
  # do NOT close $ROOT — closing the last pane deletes $WS

• claude --chrome attaches the agent to the user's actual Chrome (logged-in sessions and all) — the right tool for signups, dashboards, key retrieval, and any flow where the human must take over mid-stream (logins, payments, captchas). Prompt the agent to print a clear WAITING ON <human>: <what to do> line in its pane and poll the page rather than failing, so the human can complete the step in the browser and the agent resumes on its own.

• agent start records the argv in the layout (so layout.export can rebuild the fleet) and registers the name for agent read/send/wait.

• Claude Code panes: also name the agent inside the session. After the task prompt has been sent, follow up with the /name slash command so the Claude Code session itself carries the same name as its herdr registration (shows in the CC UI/session, not just the herdr fleet):

  herdr agent send reviewer "/name reviewer"   # literal text, no Enter
  herdr pane send-keys <pane_id> enter         # submit (send-keys is pane-level only;
                                               # get the pane_id from `herdr agent get reviewer`)

  Safe to send while the agent is mid-turn — Claude Code queues the message.

• Launch Claude Code with --dangerously-skip-permissions and Codex with --dangerously-bypass-approvals-and-sandbox for hands-off fleet runs — per-launch flags only; never edit the user's global agent config.

• An agent turning idle does not mean it succeeded — a declined turn also goes idle. Always read the pane (or check artifacts) after the wait fires.