Agent states

flockr recognizes coding agents running in panes and gives each one a state. The sidebar, the jump keys, notifications, and the CLI all use these states.

The states

State	Meaning
`working`	The agent is processing.
`blocked`	The agent is showing an approval or question and waits for you.
`done`	The agent finished and you haven't seen the result yet.
`idle`	The agent is at its prompt and there is nothing new to see.
`unknown`	An agent is present, but flockr can't classify its screen with confidence. This does not mean it finished.

done and idle are the same agent state seen from two sides: the agent is at its prompt, and done means nobody has looked at it yet.

How states look

ui.status_indicators picks the style:

State	`"dots"` (default)	`"symbols"`	Theme color
working	`●`	`◐`	`yellow`
blocked	`●`	`×`	`red`
done	`●`	`✓`	`teal`
idle	`○`	`○`	`green`
unknown	`·`	`·`	`overlay0`

The working indicator pulses unless ui.pulse_working = false. An idle agent on a fresh session it hasn't worked in yet shows a dotted ring (◌).

How flockr knows an agent's state

flockr uses two sources:

Screen detection. flockr reads the bottom of each pane and matches it against detection rules for known agents. The rules ship with each release. flockr server agent-manifests lists the active rules.
Integration hooks. An integration installs a hook or plugin into the agent. Every integration reports the agent's session identity, which flockr needs to resume the agent after a restart and to tell fresh sessions from used ones. Some integrations also report working, blocked, and idle directly.

Hooks talk to the flockr server over its socket, using the FLOCKR_PANE_ID and FLOCKR_SOCKET_PATH variables set in each pane.

To see why a pane has the state it has:

flockr agent explain w1:p2

It prints the detected agent, its state, the rule that matched, and the screen text that matched it. Add --json for scripts.

When done becomes idle

A finished agent shows as done until you see it. These settings control what counts as seeing it:

ui.seen_delay_ms (default 0): how many milliseconds a finished agent's pane must stay on screen before its done badge clears. 0 clears it at once. Set a delay, such as 1500, so you can step past done agents with prefix+a or alt+1..9 without clearing the ones you pass.
ui.seen_scope (default "pane"): "pane" counts only the focused pane, so a finished agent in a split stays done until you go into it. "tab" counts every pane in the visible tab.

Press prefix+u (mark_unread) to show the focused pane's finished agent as done again, so it comes back up in prefix+a.

Both settings are also in the settings screen under alerts, as "done badge delay" and "done badge clears".

[ui]
seen_delay_ms = 1500
seen_scope = "pane"

Keep agents in use first

ui.keep_agents_in_use_first = true keeps agents that are in use ahead of empty ones in each tab:

When an agent starts a fresh session (a new launch or /clear), its pane moves after the last agent in use in its run of adjacent agent panes, ahead of older empty sessions.
When that session takes its first prompt, the pane moves there again.
Editors, shells, and other non-agent panes keep their slots.
Fresh sessions show a dotted ring.

Agents report fresh sessions through their flockr hooks, so this needs the agent's integration. It is off by default.

To sort once instead, press prefix+shift+s (sort_panes_by_age). It orders the tab's panes by fresh agent session, oldest first, within each run of agent panes.

States from the command line

flockr agent list                                  # every agent and its state
flockr agent get reviewer                          # one agent
flockr agent wait reviewer --until blocked         # wait for a state
flockr agent prompt reviewer "Run the tests" --wait

Without --until, agent wait and agent prompt --wait match idle, done, or blocked. Focus commands mark the target seen; reads do not. See the CLI reference.