Agents · rodeo

An agent is a program in a pane that reports its state to hc. rodeo shows that state, and tells you when an agent finishes or needs you.

What counts as an agent

A program becomes an agent when it reports its state to hc with OSC 7501, the Program Status Protocol. hc keeps the state with the terminal, so every client sees the same thing: rodeo, the Herdr desktop app, and hc get.

rodeo does not read the screen to guess. A program that does not report has no state, and does not show in the agent list. Herdr TUI found some agents on the screen, so it can show more of them.

States

State	Means
● blocked	It needs you: a permission, a question or a login. An error shows as blocked too.
● working	It is on a turn.
● done	It finished a turn that you did not see yet.
○ idle	It finished, and you saw it.

An agent turns from done to idle when you look at its pane. hc keeps that as the herdr.seen label, so the Herdr app sees it too.

A space or a tab shows the most urgent state of its agents: blocked, then done, then working, then idle. Set ui.status_indicators = "symbols" for × ✓ ◐ ○ in place of dots.

The agent list

The sidebar lists every agent under the spaces, with its state, machine, space and tab. Click the label at the top right to sort it:

grouped keeps the order of spaces, tabs and panes.
priority puts the most urgent first, then the most recent change.

[ui.sidebar.agents] sets what each row shows, and rows_by_agent gives one agent its own rows. Drag the line above the list to give it more or less room.

Keys	Does
`prefix+g`	Find an agent by name. In the list, `b` `w` `i` `d` show only blocked, working, idle or done agents, and `a` shows all.
`previous_agent` / `next_agent`	Step through the agent list. Not bound by default.
`focus_agent`	Go to agent 1 to 9, with a bind such as `prefix+alt+1..9`.

Toasts

A toast tells you when an agent in the background finishes or needs you. Toasts are off by default. Turn them on in [ui.toast], or with prefix+s:

~/.config/rodeo/config.toml

[ui.toast]
delivery = "herdr"
delay_seconds = 1

`delivery`	Shows
`off`	Nothing.
`herdr`	A toast in rodeo, at `ui.toast.herdr.position`.
`terminal`	A notice from your terminal, in Ghostty, iTerm2, WezTerm and kitty.
`system`	A notice from your system: `terminal-notifier` or `osascript` on macOS, `notify-send` or `gdbus` on Linux.

rodeo waits delay_seconds, then shows the toast only if the agent is still in that state. There is no toast for the tab you look at. prefix+o goes to the pane of the last toast.

Sounds

rodeo plays a short chime when an agent in the background finishes or needs you. Sound is on by default.

~/.config/rodeo/config.toml

[ui.sound]
enabled = true
done_path = "sounds/done.mp3"       # relative to the config folder
request_path = "sounds/request.mp3"

[ui.sound.agents]
droid = "off"

On macOS rodeo plays with afplay. On Linux it tries paplay, pw-play, aplay, ffplay, mpg123 and mpv, in that order; aplay plays the built-in chimes only. Set RODEO_DISABLE_SOUND to turn sound off for one run.