herdr

What this skill does

# herdr — agent skill

you are running inside herdr, a terminal-native agent multiplexer. herdr gives you workspaces, tabs, and panes — each pane is a real terminal with its own shell, agent, server, or log stream — and you can control all of it from the cli.

this means you can:

- see what other panes and agents are doing
- create tabs for separate subcontexts inside one workspace
- split panes and run commands in them
- start servers, watch logs, and run tests in sibling panes
- wait for specific output before continuing
- wait for another agent to finish
- spawn more agent instances

the `herdr` binary is available in your PATH. its workspace, tab, pane, and wait commands talk to the running herdr instance over a local unix socket.

if you need the raw protocol or full api reference, read the [socket api docs](https://herdr.dev/docs/socket-api/).

## verified version

this skill documents herdr **v0.5.8**. commands were verified against the actual binary. do not assume newer features (like `herdr agent` subcommands) exist unless confirmed.

## concepts

**workspaces** are project contexts. each workspace has one or more tabs. unless manually renamed, a workspace's label follows the first tab's root pane — usually the repo name, otherwise the root pane's current folder name.

**tabs** are subcontexts inside a workspace. each tab has one or more panes.

**panes** are terminal splits inside a tab. each pane runs its own process — a shell, an agent, a server, anything.

**agent status** is detected automatically by herdr. the api exposes one public field for it:

- `agent_status` — `idle`, `working`, `blocked`, `done`, `unknown`

`done` means the agent finished, but you have not looked at that finished pane yet.

plain shells still exist as panes, but herdr's sidebar agent section intentionally focuses on detected agents rather than listing every shell.

**ids** — herdr v0.5.8 uses opaque workspace-scoped pane ids like `w651d456f8444f3-2`. tab ids look like `w651d456f8444f3:2`. workspace ids look like `w651d456f8444f3`. always re-read ids from `herdr pane list` before using them — do not hardcode or guess.

## discover yourself

see what panes exist and which one is focused:

```bash
herdr pane list
```

the focused pane is yours (look for `"focused": true`). other panes are your neighbors.

list workspaces:

```bash
herdr workspace list
```

## do not redirect pane output to files

**do not** use shell redirection like `> /tmp/output.txt` or `2>&1 | tee /tmp/log` when running commands in a herdr pane via `herdr pane run`. herdr's value is seeing the live terminal stream — the agent's own output, colours, formatting, and progress indicators. redirecting hides all of that and makes the pane appear frozen.

instead, observe output with:

- `herdr pane read <id> --source recent --lines N` — read what is already in the scrollback
- `herdr wait output <id> --match "pattern" --timeout N` — block until expected output appears
- `herdr pane read <id> --source visible --ansi` — get an ANSI snapshot for TUI feedback loops

## pane commands (the only way to interact with panes)

herdr v0.5.8 does **not** have `herdr agent` commands. all interaction goes through `herdr pane`:

- `herdr pane list` — list all panes, find your pane id and neighbors
- `herdr pane read <id> --source recent --lines N` — read what is on the screen
- `herdr pane send-text <id> "text"` — send text without pressing enter
- `herdr pane send-keys <id> Enter` — press a key (Enter, CtrlC, Escape, etc.)
- `herdr pane run <id> "command"` — send text + enter atomically
- `herdr pane split <id> --direction right|down [--no-focus] [--cwd PATH]` — split and create a new pane
- `herdr pane close <id>` — close a pane
- `herdr pane rename <id> "label"|--clear` — assign or clear a pane label
- `herdr pane get <id>` — get detailed info about a pane

## sending messages to a pane

`herdr pane run <id> "text"` sends text + Enter atomically and returns immediately. it does not wait for the receiving side to process the message.

```bash
# send a complete message — runs "npm test" in the pane's shell
herdr pane run w651d456f8444f3-3 "npm test"

# send text to an agent in the pane
herdr pane run w651d456f8444f3-3 "review the test coverage in src/api/"
```

`herdr pane send-text <id> "text"` sends raw text without pressing enter. use `herdr pane send-keys <id> Enter` to press enter separately:

```bash
# send text without enter
herdr pane send-text w651d456f8444f3-3 "hello"

# press enter
herdr pane send-keys w651d456f8444f3-3 Enter
```

**important**: `pane run` appends `\r` (carriage return) to the text, equivalent to pressing enter. the command runs in the pane's existing shell process — it does not start a new shell. if the pane is at an agent prompt (e.g. `>` or the pi input line), the command text will be sent to the agent, not executed as a shell command.

**there is no built-in delay or `--wait` flag on `pane run` or `pane send-text`.** both return immediately. to pace messages to an agent, use `herdr wait agent-status --status idle` between sends:

```bash
# send a message
herdr pane run w651d456f8444f3-3 "review the test coverage"

# wait until the agent is idle again
herdr wait agent-status w651d456f8444f3-3 --status idle --timeout 120000

# now send the next message
herdr pane run w651d456f8444f3-3 "also check src/utils/"
```

## spawn a new agent

split a new pane, then run the agent in it:

```bash
# split to the right without stealing focus
herdr pane split w651d456f8444f3-2 --direction right --no-focus

# parse the new pane id from the JSON response
# the response is: {"result":{"pane":{"pane_id":"w651d456f8444f3-6", ...}}, ...}

# run the agent in the new pane
herdr pane run w651d456f8444f3-6 "pi"

# wait for the agent prompt to appear (adjust match pattern for your agent)
herdr wait output w651d456f8444f3-6 --match "thinking" --timeout 30000

# give it a task
herdr pane run w651d456f8444f3-6 "review the test coverage in src/api/"
```

**do not pipe the agent's output** (e.g. `pi | tee /tmp/log`) when starting — the command text is sent to the pane's shell, not as a pipe target. let the agent's output flow naturally to the pane.

## wait patterns

`herdr wait output` watches for text in a pane's terminal output. useful for servers, builds, logs:

```bash
herdr wait output w651d456f8444f3-3 --match "ready on port 3000" --timeout 30000
herdr wait output w651d456f8444f3-3 --match "test result" --timeout 60000
herdr wait output w651d456f8444f3-3 --match "server.*ready" --regex --timeout 30000
```

`herdr wait agent-status` watches for the agent status field on a pane. useful for coding agents:

```bash
herdr wait agent-status w651d456f8444f3-3 --status done --timeout 60000
herdr wait agent-status w651d456f8444f3-3 --status idle --timeout 60000
herdr wait agent-status w651d456f8444f3-3 --status blocked --timeout 300000
```

**tip**: `wait output` matches against unwrapped recent terminal text. pane width and soft wrapping do not break matches. if you want to inspect the same transcript that the waiter matched, use `pane read --source recent-unwrapped`.

both commands exit code `1` on timeout.

## reading output

```bash
# current viewport (what is visible right now)
herdr pane read w651d456f8444f3-3 --source visible --lines 80

# recent scrollback (what was printed recently)
herdr pane read w651d456f8444f3-3 --source recent --lines 50

# without soft wrapping (best for logs)
herdr pane read w651d456f8444f3-3 --source recent-unwrapped --lines 120

# with ANSI colours preserved
herdr pane read w651d456f8444f3-3 --source visible --ansi
```

## workspace management

```bash
herdr workspace list
herdr workspace create --cwd /path/to/project
herdr workspace create --cwd /path/to/project --label "api server"
herdr workspace create --no-focus
herdr workspace focus w651d456f8444f3
herdr workspace rename w651d456f8444f3 "api server"
herdr workspace close w651d456f8444f3
```

## tab management

```bash
he