herdr

Herdr

Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the herdr CLI.

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

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 current session. Use it to inspect neighboring work, create terminal layout, start agents and commands, read output, and wait for state changes.

Learn the current CLI

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

herdr --help

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

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session
herdr machine

Do not run bare herdr for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments. Commands such as herdr workspace create are valid with defaults and will execute.

Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.

Understand layout, panes, and agents

Choose the primitive that matches the job:

• Workspace, tab, and pane topology organize terminal locations.
• Pane commands control raw terminals, shells, tests, servers, input, and output.
• Agent commands control the recognized coding agent currently occupying a pane.

A pane exists whether or not it contains an agent. agent start requires an existing available shell pane and never creates, splits, or moves layout. Use pane commands for ordinary processes. Use agent commands when Herdr must validate agent identity or interpret idle, working, blocked, done, and unknown lifecycle states.