Agent status in Hive and the report-agent protocol

How Hive knows an agent is working, needs input or is done, which agents it recognises, the bell and notifications, and how scripts report their own status.

Hive shows what each agent is doing: working, needs input (a permission prompt or a question), done (finished while you were elsewhere) or idle. It never guesses: an agent it has no rules for shows no status rather than a wrong one, and Hive never answers an agent's prompts for you.

How Hive knows

Which agent. The daemon looks at the program in the foreground of each terminal and recognises agents by their command line, also through launchers such as node, npx, uvx or sh -c. So an agent you type into a shell is recognised as well as one started with hive new. An unrecognised program is checked again every two seconds, in case a launcher starts the agent a moment later.
What it is doing. Per-agent screen rules read the agent's screen: a spinner or “esc to interrupt” means working, an approval prompt means needs input. The rules are shared with herdr. To avoid flicker, an agent has to look idle for a second before Hive reports it idle.
Done is Hive's own: an agent that goes from working to idle while you aren't viewing it is marked done until you open it.

Detection runs in the daemon, so status keeps updating while no window is open, and every window sees the same thing. hive list shows it too.

Recognised agents

With status rules (23): Claude Code, Codex, Gemini CLI, OpenCode, GitHub Copilot, Cursor Agent, Amp, Antigravity, Cline, Devin, Droid, Grok, Hermes, Kilo Code, Kimi, Kiro, Letta, Maki, Muse, Oh My Pi, Pi, Qoder, Qwen Code.

Recognised and launchable, without status rules (4): Aider, Crush, Goose, Truss. They can report their own status (below).

hive agents lists the agents on your machine; hive agents -a lists all of them. Any other program can be added under [agents.<name>].

Getting your attention

The sidebar marks the agent, and its space, as soon as it needs input or is done.
The terminal bell rings when an agent you aren't viewing needs input or finishes. Many terminals turn the bell into a flash, a sound or an urgent window. [notifications] bell = false turns it off.
With desktop notifications on, Hive also runs notify-send (or your own command) with a title and message.
With the Obsidian journal on, each finished turn is logged in today's daily note.

Reporting status yourself: report-agent

An agent without rules, a wrapper script or your own tool can tell Hive its state. Every session gets two environment variables: HIVE_SESSION_ID and HIVE_BIN_PATH (the hive binary next to the daemon).

"$HIVE_BIN_PATH" report-agent --agent mybot --state working
"$HIVE_BIN_PATH" report-agent --agent mybot --state blocked --message 'approve the migration?'
"$HIVE_BIN_PATH" report-agent --agent mybot --state idle
"$HIVE_BIN_PATH" release-agent --agent mybot   # hand back to screen detection

Rule	Detail
States	`idle`, `working`, `blocked` (shown as needs input) or `unknown`
Precedence	A report overrides screen detection for that session until `release-agent`
Lifetime	The report lapses when the foreground program changes, so an agent that exits without releasing doesn't leave a stale status
Ordering	`--seq N` numbers reports; one not above the last is ignored. The default is the current time in milliseconds
Limits	Agent name up to 64 characters, message up to 200
Session	Defaults to `$HIVE_SESSION_ID`; pass an id to report for another session

For example, a Claude Code hook can report blocked from a Notification hook and idle from a Stop hook, though Hive already recognises Claude Code without one.