Agents

Preview docs describe unreleased preview builds. Stable docs remain at /docs/.

Herdr is built for running more than one coding agent at a time. Each agent stays in a real terminal pane with its shell, logs, prompts, and running processes intact. Herdr tracks which panes contain agents, rolls their state up to tabs and workspaces, and lets you jump straight to the pane that needs attention instead of polling every terminal by hand.

Supported agents

Automatic detection works out of the box for common coding agents. The important difference is not whether Herdr can see an agent. It is which signal is allowed to author idle, working, and blocked.

Agent	State authority	Integration role
Pi	lifecycle hooks when installed; otherwise PTY/screen	state and session
OMP	lifecycle hooks when installed	state
GitHub Copilot CLI	PTY/screen	session
Kimi Code CLI	PTY/screen	session
Hermes Agent	lifecycle hooks when installed; otherwise PTY/screen	state and session
Qoder CLI	PTY/screen	session
Droid	PTY/screen	session
OpenCode	lifecycle plugin when installed; otherwise PTY/screen	state and session
Kilo Code CLI	lifecycle plugin when installed; otherwise PTY/screen	state and session
Claude Code	PTY/screen	session
Codex	PTY/screen	session
Cursor Agent CLI	PTY/screen	session
Amp	PTY/screen	none
Grok CLI	PTY/screen	none
Antigravity CLI	PTY/screen	none
Kiro CLI	PTY/screen	none

Detected but less thoroughly tested: Gemini CLI and Cline. Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API.

Status authority

Herdr first detects the foreground process in each pane. After that, each pane has one status authority.

For agents with complete lifecycle hooks, the integration is authoritative when it is installed and actively reporting for the running pane. Herdr uses those hook reports for idle, working, blocked, and session identity. It does not also run PTY/screen state fallback for that same lifecycle authority. This avoids two competing sources of truth.

For agents without complete lifecycle hooks, Herdr uses PTY-first detection. Terminal render activity means the agent is probably working. When the terminal becomes quiet, Herdr reads the recent pane screen and asks one strict question: does the visible agent UI match a known blocked prompt? If yes, the pane is blocked. If not, the pane is idle.

Herdr briefly ignores detection after a new agent process appears, and after input, mouse events, or pane resize. Those events can make a terminal UI redraw even when the agent did not resume work. Once the quiet window passes, normal detection starts again from fresh PTY activity.

Claude Code, Codex, GitHub Copilot CLI, Droid, Kimi Code CLI, Qoder CLI, and Cursor Agent CLI integrations are intentionally not lifecycle authorities. They provide native session identity for restore, but their hooks do not cover the whole lifecycle. They can miss permission approval results, escape interrupts, or other transitions. For those agents, Herdr still uses PTY/screen state detection.

Blocked state

Blocked detection is deliberately strict for PTY/screen agents. Herdr treats active terminal output as working; it only asks whether the agent is blocked after PTY activity becomes quiet. If the screen does not match a known blocked prompt shape, Herdr falls back to idle.

This means unusual new agent prompts may initially show as idle instead of blocked until Herdr learns that screen shape. It also means opening an agent menu, moving a selection, or resizing a pane may delay state changes briefly. Those interactions should not make Herdr send input or take destructive action; they only affect the visible status and waits.

Herdr can run inside tmux as the outer terminal environment. Agent detection does not inspect tmux sessions launched inside a Herdr pane. If a shell framework auto-enters tmux inside Herdr, Herdr sees tmux as the pane process instead of the agent behind it.

State rollups

The sidebar rolls state upward.

A blocked agent makes its pane, tab, and workspace look blocked. A working agent makes the workspace look active. A done agent stays visible until you view it.

This is the main Herdr workflow: start several agents, let them work in parallel, and use the sidebar to see which project needs a decision, which one is still running, and which one is ready to review.

Direct integrations

Install integrations for agents that expose hooks or plugins:

herdr integration install pi
herdr integration install omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install cursor
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install qodercli

Check installed integration versions:

herdr integration status

Show only outdated integrations:

herdr integration status --outdated-only

Custom agent labels

You can rename an agent target for display:

herdr agent rename 1-1 reviewer
herdr agent rename reviewer --clear

Targets accept terminal IDs, unique agent names, detected or reported agent labels, and legacy pane IDs.

Custom status labels

Integrations can report a visual status label without changing semantic state.

herdr pane report-agent 1-1 \
  --source custom:indexer \
  --agent docs-bot \
  --state working \
  --custom-status indexing

state controls waits, notifications, and rollups. custom-status is only display text.

Start agents from the CLI

Use herdr agent ... commands when you want a terminal to be treated as an agent target. Agent targets show up in agent list, can be read or sent input by agent name, can be waited on by agent state, and can be directly attached.

Spawn an agent into Herdr from a script:

herdr agent start reviewer --cwd ~/project --split right -- pi

You can place that agent in a specific workspace or tab:

herdr agent start docs --workspace 1 --tab 1-1 -- claude

Use herdr pane ... commands for ordinary terminals, servers, tests, shells, and low-level terminal input. For example, use pane split and pane run for cargo test, not agent start, unless that terminal is intentionally being treated as an agent target.

Attach directly to an agent

Attach your current terminal to one agent terminal instead of the full Herdr UI:

herdr agent attach reviewer

Detach with ctrl+b q. Send a literal ctrl+b with ctrl+b ctrl+b.

Scroll with the mouse wheel or plain page up/page down. Normal input jumps back to the bottom.

Use --takeover if another direct attach client already owns input:

herdr agent attach reviewer --takeover

Use herdr terminal attach <terminal_id> when you want the same direct attach behavior for a non-agent terminal.