Herdr

Parent: Integrations.

Herdr is a terminal workspace that hosts agent panes. When Rho runs inside a Herdr pane, integration turns on by itself. You do not install a plugin, run an init command, or edit Rho config.

Herdr support is Unix-only. On other platforms Rho ignores Herdr environment variables.

What you get

Feature	Behavior
Agent state	Rho reports idle, working, and blocked so Herdr can show pane status
Session restore	After a Herdr server restart, the pane reopens the same Rho session
Subagent attach	Click a subagent row in the activity rail to open the in-place attach view. rho attach <id> remains available for another terminal.
Image paste	A single-line paste of an image path becomes an attachment instead of plain text
Image previews	Standard Kitty graphics, rendered natively by Herdr 0.9.2 or later

Nothing extra is required after you start Rho under Herdr.

How Rho detects Herdr

Rho enables Herdr when all of these are true:

• the process runs on Unix
• HERDR_ENV=1
• HERDR_SOCKET_PATH is a non-empty path to Herdr's local socket
• HERDR_PANE_ID is a non-empty pane id

Herdr sets those variables for processes it launches. You normally do not set them by hand.

Rho talks to Herdr over that Unix socket with short timeouts. Failed or timed-out reports are ignored so a stuck host never blocks the session.

Agent state

Rho keeps Herdr in sync with the session:

State	When
working	A model turn or tool run is in progress, or an attached subagent is still running
blocked	Rho waits on you (approval, questionnaire), auth is missing, a goal is blocked, or an attached run failed
idle	The session is resting and not waiting on user input

On exit, Rho releases the agent marker for the pane.

Interactive sessions and rho run both report state when they detect Herdr. rho attach <id> reports state for the watched run and releases on detach.

Session restore

Rho reports a resume command for each saved session, so Herdr can reopen that session in the same pane and directory after its server restarts:

rho [--config <path>] [--agent <id>] [--no-system-prompt] [--no-tools] [--no-subagents] \
  [--model <provider/model>] [--auth <profile>] [--reasoning <level>] \
  [--permission-mode <mode>] --resume <session-id>

Launch flags are repeated as given. Model, auth, reasoning, and permission mode are added only where the session differs from what a plain relaunch would select (your config, plus the --agent definition's model when one was given), for example after another pane saves a different model. Otherwise the restored session reads them from config, exactly like a plain rho --resume. Rho re-reports the command when the session, its selection, or the config file changes, including while the pane is idle, and retries until Herdr accepts it. Switching to another session with /resume moves the pane to that session.

A session that is not saved yet (before the first prompt, after /new, or with --no-save) has no resume command. Resume needs Herdr 0.9.2 or later. To turn it off, set [session] resume_agents_on_restore = false in Herdr's config.

rho attach, rho run, and rho acp report state but no resume command. rho run and rho acp report under their own source, so one started from a tool inside an interactive pane cannot clear that session's resume command.

Watch a subagent

Activating a subagent row, or choosing one from /attach, opens a read-only attach view in the same terminal. The parent session keeps streaming. Press q or Escape to return. Detaching does not stop the delegated run.

rho attach <id> still starts the same viewer as its own process when you want another terminal. See attachment and artifacts.

Images and graphics

Hosts such as Herdr may paste clipboard images as a filesystem path. Rho treats a single-line paste of a PNG, JPEG, GIF, or WebP path as an image attachment. Details: attachments.

In-feed image previews use standard Kitty graphics written to the pane, which Herdr 0.9.2 and later render natively. Rho does not use a Herdr-specific graphics API. Older Herdr releases may leave blank rows where previews should appear; upgrade Herdr to fix this.

See documents and images.

Check the integration

In the interactive TUI, run /doctor. The Herdr row reports:

Status	Meaning
not configured	Rho is not running inside Herdr (healthy when you are outside Herdr)
connected	Herdr env is set and the socket accepted a connection
unreachable	Herdr env is set but the socket did not accept a connection (shown as a failure)
unknown	Herdr is configured but reachability could not be determined (shown as a warning)

Related

• Integrations - other built-in integrations
• Interactive TUI - session UI, /doctor, and rho attach
• Subagent attachment - run artifacts and detach behavior
• Attachments - image and document paste
• Documents and images - thumbnail paint paths
• Development - use PTY tests for regressions; use Herdr for exploratory checks