Agents

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.

Agent	Idle / done	Working	Blocked
Pi	yes	yes	partial
Claude Code	yes	yes	yes
Codex	yes	yes	yes
Droid	yes	yes	yes
Amp	yes	yes	yes
OpenCode	yes	yes	yes
Grok CLI	yes	yes	yes
Hermes Agent	yes	yes	yes
Kiro CLI	yes	yes	no
GitHub Copilot CLI	yes	yes	yes

Detected but less thoroughly tested: Gemini CLI, Cursor Agent, Cline, and Kimi.

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.

How detection works

Herdr combines three signals:

1. foreground process detection
2. terminal output heuristics
3. integration state reports

Process detection tells Herdr which pane owns an agent. Heuristics infer state when no hook is available. Integrations provide the most precise semantic state.

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 claude
herdr integration install codex
herdr integration install opencode
herdr integration install hermes

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.

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.