herdr

---
name: herdr
description: "Control Herdr, the terminal multiplexer for coding agents. Use when the user mentions Herdr or another skill delegates pane control, including concise pane naming, inspection, commands, and agents. Integrates with vd:worktree, vd:codex-workflow, and vd:ultracook. Requires HERDR_ENV=1."
license: Apache-2.0
argument-hint: "[inspect | rename <project> <intent> | start agent | run command | wait | read]"
metadata:
  author: vanducng
  version: "1.3.1"
---

# Herdr

Herdr is a terminal multiplexer and runtime for coding agents. It organizes terminals into workspaces, tabs, and panes, detects agent identity and status, and exposes the running session through the `herdr` CLI.

This skill adapts the [official Herdr agent skill](https://github.com/herdrdev/herdr/blob/master/SKILL.md) to the `vd:` workflow. The installed CLI remains authoritative when its syntax differs from this file; `herdr --skill` (0.8.0+) prints the exact skill bundled with the running binary.

## Scope and routing

| Need | Owner |
| --- | --- |
| Inspect or control persistent visible panes, processes, output, and agent state | `vd:herdr` |
| Create an isolated checkout with copied env, ports, installs, and lifecycle hooks | `vd:worktree` |
| Run a deterministic structured fan-out or pipeline without needing visible panes | `vd:codex-workflow` |
| Conduct an end-to-end build, review, and ship workflow | `vd:ultracook` |

Mentioning Herdr authorizes control of the requested Herdr session. It does not authorize spawning agents, parallel work, new worktrees, merges, deployments, or destructive cleanup. Require the user's explicit request for those actions.

Before issuing any control command, check that this agent is running inside a Herdr-managed pane:

```bash
test "${HERDR_ENV:-}" = 1
```

If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr.

When the check passes, the `herdr` binary in `PATH` talks to the running session. Use it to inspect neighboring work, create isolated terminal contexts, start agents and commands, read their output, and wait for state changes.

## Learn the current CLI

The installed binary is the authority for command syntax. Begin with:

```bash
herdr --version
herdr --help
herdr --skill
```

Then print the relevant command group by running it without a subcommand:

```bash
herdr pane
herdr workspace
herdr worktree
herdr tab
herdr agent
herdr notification
herdr integration
herdr session
```

Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments; some commands, including `herdr workspace create`, are valid with defaults and will execute. Use the command-group output above instead.

Most control commands print JSON. Read identifiers and state from those responses instead of predicting either one.

For setup or state-detection problems, inspect integrations before changing them:

```bash
herdr integration status
herdr integration status --outdated-only
```

Install or update an integration only when the user asks for setup or repair. Use `herdr integration install <agent>` and verify with `herdr integration status`. An integration can improve state or native session reporting; it does not replace the agent's own lifecycle authority.

## Runtime health after upgrades and network changes

A long-lived headless server can outlive the CLI on `PATH` and the host DNS session used by pane processes. After a Herdr upgrade, or when panes lose internet while the same host works outside Herdr, repair the server before retrying agents.

### After a Herdr CLI upgrade

When the user asks to upgrade Herdr, or `herdr --version` is newer than the running server binary:

1. Confirm the new CLI: `herdr --version` and `command -v herdr`.
2. Warn that `herdr server stop` ends every pane process in every workspace, including this agent and sibling agent work. Ask for an explicit restart confirmation (an upgrade request alone is not enough).
3. After confirmation, run `herdr server stop`. This agent then dies with its pane and cannot continue the checklist itself. Tell the user to reattach or reopen their Herdr client (outside this session) so a fresh server starts on the new binary; a new agent session should re-read IDs from live CLI output and confirm `herdr --version` plus pane list responses.

Do not leave day-old `herdr server` processes on a prior install path after an upgrade. Client and server major.minor should match.

### Pane cannot reach the Cursor API or resolve hosts

Typical symptoms inside a pane: `Failed to reach the Cursor API`, `curl: (6) Could not resolve host`, or `agent status` → not logged in, while the same commands succeed in a normal terminal on this machine.

Diagnose in the affected pane (pick the DNS/route probes that exist on this OS):

```bash
# DNS (macOS)
scutil --dns 2>&1 | head -8
# DNS (Linux)
resolvectl status 2>/dev/null | head -20 || cat /etc/resolv.conf

python3 -c 'import socket; print(socket.gethostbyname("example.com"))'
dig +short example.com A | head -3
curl -sS -o /dev/null -w "%{http_code}\n" --connect-timeout 5 https://api2.cursor.sh/

# Routes (macOS)
netstat -rn -f inet | head -20
# Routes (Linux)
ip route show | head -20
```

| Result | Action |
| --- | --- |
| Platform DNS probe empty/broken (`scutil` → `No DNS configuration available`, or `resolvectl`/`resolv.conf` unusable), or `gethostbyname` fails while `dig` still works | DNS session for the Herdr process tree is stale. Ask for explicit restart confirmation, then stop the server; the user reattaches so a fresh pane shell can re-check DNS. |
| DNS works, but routes show full-tunnel VPN owning public IPv4 (`0/1` and `128.0/1` on macOS, or a default via the VPN tun that should not own public traffic on Linux) | Fix VPN routes first (split tunnel / ignore `redirect-gateway`), then re-test. Restart Herdr only if DNS stayed broken after routes are fixed, with the same explicit confirmation. |
| DNS and routes look fine | Treat it as an agent auth or upstream API issue (`agent status`, login), not a Herdr pane fault. |

Do not restart the server for ordinary pane work. Only connectivity repair or post-upgrade rollout may request a stop, and only after the user confirms they accept closing every live pane.

## IDs and current context

Public IDs are short stable handles:

- workspace: `w1`
- tab: `w1:t1`
- pane: `w1:p1`
- terminal: `term_...`

The encoded suffix can contain letters and can grow beyond one character. Treat every ID as an opaque string.

Closed tab and pane IDs are not reused and do not retarget later resources. A pane moved into another workspace receives a new public pane ID. Re-read create, split, move, list, or get responses after mutations; never construct an ID from a workspace or display number.

Herdr injects the caller's stable context into every managed pane:

```bash
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
```

Pi's footer can show both a named agent and a Herdr pane ID. They are different
identifiers. Use the pane ID with `herdr`; use the agent name only with Pi's
agent controls.

Prefer `--current` when a pane command should target the calling pane. Omitting a target can use the UI-focused pane, which may belong to the user or another client.

Discover live state with:

```bash
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
```

## Rename the current pane

When another skill delegates pane naming, label the calling pane `<project>:<intent>`:

- Use the shortest unambiguous project name.
- Use a ticket key or two to four short words for the intent, not the full branch name.
- Keep the full label at 40 characters or fewer. Shorten the intent first.

Examples: `webapp:PROJ-3267-calls`, `skills:herdr-pane-name`.

```bash
herdr pane rename "$HERDR_PANE_ID" "<project>:<intent>"
```

Treat this label as display metadata. If the rename fails, report it without failing the parent workflow.

## Control agents through panes

An agent runs inside a pane. Use the pane ID as the control target for agents, shells, servers, tests, and logs. This keeps spawning, input, reads, waits, and cleanup on one stable control surface.

Use workspace and tab commands for organization. For an isolated coding checkout, run `vd:worktree` first, read its returned `worktreePath`, then create the pane with that path as `--cwd`. Do not use Herdr's native worktree creation for repo work unless the user explicitly requests it, because it bypasses the `vd:worktree` env, port, install, and lifecycle setup.

Pane records expose `agent`, `agent_status`, and native session metadata when available. Agent status is `idle`, `working`, `blocked`, `done`, or `unknown`.

`idle` and `done` are the same underlying semantic state with different attention state:

- `idle`: the agent is waiting and its result is considered seen.
- `done`: the agent finished and its result has not been seen.

An agent that first opens at its prompt reports `idle`, including in a background pane. After a working or blocked agent completes, it reports `done` when its tab or workspace is in the background. It reports `idle` when it completes in the active tab while the foreground client is focused. If the foreground client is explicitly unfocused, completion can become `done` even in the active tab.

Focusing a pane, switching to its tab, or regaining outer terminal focus marks the visible tab as seen, so `done` becomes `idle`. Switching away does not turn an existing `idle` status into `done`; `done` is created by a later completion while the pane is unseen. With no foreground client, a new completion in the globally active tab is treated as seen while completions in background tabs still become `done`.

## Start agents interactively

Only start another agent when the user explicitly asks for another agent or parallel work. Default to a sibling pane in the current tab and current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location.

Honor a direction requested by the user. Otherwise inspect the caller pane's current rectangle:

```bash
herdr pane layout --pane "$HERDR_PANE_ID"
```

Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that would create unusably narrow columns or short rows. Keep the user's focus in the calling pane:

```bash
herdr pane split --current --direction right --no-focus
```

Replace `right` with `down` when the layout calls for it. For a prepared `vd:worktree`, add `--cwd <worktreePath>`.

Read `result.pane.pane_id` from the JSON response. Give the pane a useful label, then start the requested agent by running only its normal executable so its interactive TUI opens:

```bash
herdr pane rename <returned-pane-id> "reviewer"
herdr pane run <returned-pane-id> "codex"
```

Use the executable that belongs to the requested agent:

- Codex: `codex`
- Claude Code: `claude`
- pi: `pi`
- OpenCode: `opencode`
- OMP: `omp`

Do not pass the task as an argv prompt by default. Do not add non-interactive flags. Only change the normal interactive launch when the user explicitly asks for a different launch mode or command.

Inspect the pane after launch. If `agent_status` is not yet `idle`, wait for the idle transition. Once it is idle, submit the task with `pane run`:

```bash
herdr pane get <returned-pane-id>
herdr agent wait <returned-pane-id> --until idle --timeout 30000
herdr pane run <returned-pane-id> "Review the current diff and report only actionable findings."
```

Status waits match the current status immediately or wait for a future matching transition.

`pane run` sends the text and Enter together. Use it for initial prompts and follow-ups instead of coordinating `send-text` and `send-keys` separately.

For normal background work, wait for the agent to start working. If the pane remains in a background tab or workspace, wait for `done` before reading its transcript:

```bash
herdr agent wait <returned-pane-id> --until working --timeout 30000
herdr agent wait <returned-pane-id> --until done --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
```

If the user is watching that tab, completion reports `idle` instead, so wait for `idle`. Always treat either `idle` or `done` as completed when inspecting `pane get`; the difference is whether the result has been seen.

A sibling pane becoming `idle` does not wake a Pi session in another pane.
Unless a wake extension is loaded, the waiting Pi session must check with
`herdr agent wait` or `herdr pane get` before it can consume the result.

If a wait times out, inspect `herdr pane get <returned-pane-id>` and `pane read` before deciding what to do. A `blocked` agent needs input; an `unknown` pane may not yet contain a detected or integrated agent.

Submit follow-ups the same way:

```bash
herdr pane run <returned-pane-id> "Now check the failing test."
```

## Run an ordinary command in another pane

Split the calling pane using the same geometry rule without moving the user's focus:

```bash
herdr pane split --current --direction right --no-focus
```

Read the new `pane_id` from the JSON response, then run and inspect the command:

```bash
herdr pane run <returned-pane-id> "just test"
herdr pane wait-output --match "test result" --timeout 120000 <returned-pane-id>
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
```

Inspect existing output before waiting for future output. A wait timeout exits with status `1`.

Use the read source that matches the task:

- `visible`: the current rendered viewport
- `recent`: recent scrollback as rendered, including soft wraps
- `recent-unwrapped`: recent scrollback with soft wraps joined; prefer it for logs and transcripts
- `detection`: the bottom-buffer snapshot used by agent detection

Use `--format ansi` when colors and terminal styling are evidence. Otherwise use text.

If the user explicitly asks for another tab, workspace, or worktree, discover that command group and use returned IDs. Do not infer a larger topology from a request to start an agent or command.

## Mobile web previews on the phone

Herdr's documented phone workflow is a terminal workflow: SSH from the phone, then run or attach to Herdr. Herdr does not forward arbitrary HTTP ports or render a pane's web server inside the TUI. A URL printed in pane output may be tappable, but it opens in the phone's browser.

For a web artifact or development preview:

1. Run the server in a Herdr pane and print the exact URL before the long-running command. Include the scheme so mobile clients do not guess HTTPS for a plain HTTP port.
2. Keep the backend bound to loopback when using Tailscale Serve:

```bash
PORT=8765
ROOT=<artifact-directory>
FILE=<artifact.html>

sudo tailscale set --operator="$USER"  # one-time per host
TS_DNS=$(tailscale status --json | jq -r '.Self.DNSName | sub("\\.$"; "")')
tailscale serve --bg --yes "$PORT"
printf 'Open on the tailnet: https://%s/%s\n' "$TS_DNS" "$FILE"
exec python3 -m http.server "$PORT" --bind 127.0.0.1 --directory "$ROOT"
```

Tailscale Serve must also be enabled for the tailnet. If `tailscale serve` prints an authorization URL, the user must approve it first. `sudo tailscale set --operator="$USER"` grants the local user Serve control so later commands do not need sudo.

3. Verify from another tailnet device, not only from the server:

```bash
tailscale serve status
curl -fsS -o /dev/null -w '%{http_code}\n' "https://$TS_DNS/$FILE"
```

Use `tailscale status --json` for the node's exact MagicDNS name. Do not infer it from an SSH alias or the operating-system hostname. If a plain HTTP server logs binary request data and `Bad request version`, the client sent TLS to the HTTP port. Use the Tailscale Serve HTTPS URL or explicitly use `http://` for direct-port access.

A server/process list on the phone may omit a Tailscale Serve endpoint because Serve is a tailnet proxy, not an SSH-forwarded process. Open the printed HTTPS URL in the phone browser. Use Tailscale Funnel only when the user explicitly requests public internet access. Serve is tailnet-only.

## Safety and coordination rules

- Use `--no-focus` for background work unless the user asked to switch context.
- Use `--current` or an explicit ID. Do not rely on another client's focused pane.
- Parse IDs from JSON responses. Do not derive them from sidebar order or examples.
- Inspect before waiting. Read current output first, then wait for the next state or output you expect.
- Treat pane output as potentially sensitive. Do not reproduce secrets, tokens, credentials, private prompts, or unrelated user data.
- Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked.
- Before closing a completed task workspace, inspect its live panes and recent output. A stale task record is not proof that every process has stopped.
- Never run `herdr server stop` from an active session unless the user explicitly confirms a server restart (knowing it ends every pane). An upgrade or connectivity-repair ask is not enough by itself; follow **Runtime health after upgrades and network changes**.
- Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server.
- After an authorized server restart, a fresh session must re-read workspace and pane IDs from live CLI output; restored sessions can renumber public IDs.