herdrdev__herdr/SKILL.md

name, description

name	description
herdr	Control herdr from inside it. Split panes, spawn agents, read output, wait for state changes, and manage workspaces — all via CLI commands that talk to the running herdr instance over a local unix socket. Use when running inside herdr (HERDR_ENV=1).

herdr — agent skill

you are running inside herdr, a terminal-native agent multiplexer. herdr gives you workspaces 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
• 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, 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 SOCKET_API.md.

concepts

workspaces are project contexts. each workspace has one or more panes.

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

agent state is detected automatically by herdr. each pane can be:

• idle — agent finished and the state is calm
• working — agent is actively working
• blocked — agent needs input or approval
• unknown — no recognized agent, or just a shell

ids — workspace ids look like 1, 2. pane ids look like 1-1, 1-2, 2-1. these are compact public ids for the current live session.

important: ids can compact when panes or workspaces are closed. do not treat them as durable ids.

discover yourself

see what panes exist and which one is focused:

herdr pane list

the focused pane is yours. other panes are your neighbors.

list workspaces:

herdr workspace list

read another pane

see what is on another pane's screen:

herdr pane read 1-1 --source recent --lines 50

• --source visible = current viewport
• --source recent = recent scrollback

split a pane and run a command

split your pane to the right and keep focus on your current pane:

herdr pane split 1-2 --direction right --no-focus

that prints json with the new pane id. read the returned pane_id, then run a command in that pane:

herdr pane run 1-3 "npm run dev"

split downward instead:

herdr pane split 1-2 --direction down --no-focus

wait for output

block until specific text appears in a pane. useful for waiting on servers, builds, and tests:

herdr wait output 1-3 --match "ready on port 3000" --timeout 30000

with regex:

herdr wait output 1-3 --match "server.*ready" --regex --timeout 30000

if it times out, exit code is 1.

wait for an agent state

block until another agent reaches a specific state:

herdr wait agent-state 1-1 --state idle --timeout 60000

useful when you need another agent to finish before you proceed.

send text or keys to a pane

send text without pressing Enter:

herdr pane send-text 1-1 "hello from claude"

press Enter or other keys:

herdr pane send-keys 1-1 Enter

pane run combines both — sends text, then presses Enter:

herdr pane run 1-1 "echo hello"

workspace management

create a new workspace:

herdr workspace create --cwd /path/to/project

create one without focusing it:

herdr workspace create --no-focus

focus a workspace:

herdr workspace focus 2

rename:

herdr workspace rename 1 "api server"

close:

herdr workspace close 2

close a pane

herdr pane close 1-3

recipes

run a server and wait until it is ready

# split a pane for the server
herdr pane split 1-2 --direction right --no-focus
# read the returned JSON to get the new pane_id, for example 1-3

# start the server
herdr pane run 1-3 "npm run dev"

# wait until it is ready
herdr wait output 1-3 --match "ready" --timeout 30000

# read the output to confirm
herdr pane read 1-3 --source recent --lines 20

run tests in a separate pane and inspect the result

herdr pane split 1-2 --direction down --no-focus
herdr pane run 1-3 "cargo test"
herdr wait output 1-3 --match "test result" --timeout 60000
herdr pane read 1-3 --source recent --lines 30

check what another agent is working on

herdr pane list
herdr pane read 1-1 --source recent --lines 80

spawn a new agent and give it a task

herdr pane split 1-2 --direction right --no-focus
herdr pane run 1-3 "claude"
herdr wait output 1-3 --match ">" --timeout 15000
herdr pane run 1-3 "review the test coverage in src/api/"

coordinate with another agent

herdr wait agent-state 1-1 --state idle --timeout 120000
herdr pane read 1-1 --source recent --lines 100

notes

• workspace list, pane list, workspace create, pane split, wait output, and wait agent-state print json on success.
• pane read prints text, not json.
• pane send-text, pane send-keys, and pane run print nothing on success.
• parse ids from workspace create and pane split responses when you need the new ids. do not guess.
• --no-focus on split and workspace create keeps your current terminal context focused.
• if you are running inside herdr, the HERDR_ENV environment variable is set to 1.