Herdr

Herdr

Herdr's CLI controls terminal panes through a local socket; it provides neither native agent-to-agent communication nor shared memory. It works with Pi, Codex, Claude Code, Cursor CLI, and other terminal agents. Native integrations improve detection, status accuracy, and session restoration.

Preconditions

Run the controlling agent inside Herdr in Ghostty. Verify access and workspace scope:

test "${HERDR_ENV:-}" = "1"
test -n "${HERDR_WORKSPACE_ID:-}"

If either fails, tell the user this agent must be launched inside Herdr; do not claim access to other agents.

One-time installation:

npx skills add ogulcancelik/herdr --skill herdr -g

Inspect, message, wait, read

Append --session <name> to every Herdr command. HERDR_SESSION alone can silently select an already-running server. Discover pane IDs; never guess them.

herdr pane list --workspace "$HERDR_WORKSPACE_ID" --session <name>
herdr pane read <pane-id> --source recent-unwrapped --lines 200 --session <name>

# For TUI agent composers, separate text from Enter
herdr pane send-text <pane-id> "Check the failing tests and report back." --session <name>
sleep 1
herdr pane send-keys <pane-id> enter --session <name>

# Confirm submission, then wait for completion (idle if the integration uses it)
herdr agent wait <pane-id> --status working --timeout 120000 --session <name>
herdr agent wait <pane-id> --status done --timeout 120000 --session <name>
herdr pane read <pane-id> --source recent-unwrapped --lines 200 --session <name>

Stay in the current workspace. Read before messaging; send nothing for inspection-only requests. Confirm submission through a native status transition to working/blocked after Enter, never merely changed pane content. Wait for done, idle, or blocked, then read again; do not assume the prompt was acted on. Corroborate idle with pane text as described below.

When coordinating agents, share missing context, prevent duplicate work, and return one combined summary.

Do not close, rename, move, resize, or reconfigure panes you did not create. Create or close panes only when the user explicitly asks. “Use the Herdr skill” means execute the CLI workflow, not merely explain it.

Operational details

Sessions and targeting

• Use named herdr session stop <name> / herdr session delete <name> for destructive operations. Never use herdr server stop; it targets the ambient server.
• Targets are <session>:<pane-id>. Pane IDs contain a colon (w1:p2); split on the first colon only.
• CLI calls do not auto-start a server. Start headless with herdr server --session <name>.
• Managed processes receive HERDR_ENV=1 and HERDR_PANE_ID. Inside nested tmux, $TMUX wins: treat the pane as tmux.
• Use an isolated named session, never default, for risky experiments. Re-check herdr session list --json --session <name> immediately before stopping or deleting.

Input

• pane send-text types without submitting. pane run sends text + Enter and works at shell prompts, but TUI composers (Claude Code, Cursor CLI) may swallow Enter as part of a paste. Use separate send-text, ~1s pause, then send-keys <pane> enter calls for TUIs.
• C0 control bytes (e.g. ASCII 0x1f) trigger terminal actions and can erase typed text. Use U+2063 INVISIBLE SEPARATOR for invisible text markers.
• Slash-command autocomplete may consume the first Enter to close the popup or fill an argument placeholder. escape dismisses the popup while preserving text.

Reading and status

• pane read --lines N returns empty output if N is below viewport height. Request at least 200 lines and at least the viewport height; trim locally with tail -n N.
• pane get .cwd is fixed at creation; .foreground_cwd is live.
• Use pane read --format ansi to distinguish placeholder text from human drafts: suggestions are dim (SGR-2) or dark truecolor; typed input renders normally. Plain text cannot reliably distinguish them.
• herdr agent get <pane> reports native working/idle/done/blocked/unknown status; prefer it to regex guesses. Long-running foreground tools may still report idle; check busy banners such as "esc to interrupt" before treating the pane as free or stale.
• Native waits: herdr agent wait <pane> --status <s> --timeout MS, herdr wait agent-status <pane> --status <s> --timeout MS, and herdr wait output <pane> --match <text>.
• Socket protocol >=16 offers pane.agent_status_changed and pane.output_matched events. Prefer events, with polling as a backstop.
• Scripts can register via pane report-agent and report idle/working/blocked.