From herdr
Monitors and triages a fleet of agents in herdr, and explains why a herdr agent's detected state looks wrong. Teaches the detection-AUTHORITY model (lifecycle-state hooks vs screen-manifest detection), state roll-up across pane/tab/workspace, a triage workflow for finding who needs attention, and a debugging path with `herdr agent explain`. Defers raw command syntax to the vendored herdr skill and live `herdr --help`. Triggers: 'which herdr agent needs attention', 'why does herdr show my agent as idle/blocked', 'monitor my agents status', 'an agent is stuck/blocked in herdr', 'herdr agent state is wrong / explain detection', 'is my agent done in herdr'.
How this skill is triggered — by the user, by Claude, or both
Slash command
/herdr:herdr-agent-monitoringThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are watching many agents at once. The skill is reading herdr's rolled-up state correctly, trusting it where it is authoritative, and knowing when (and how) to distrust it. This is judgment, not syntax — for exact commands, defer to the live CLI and the vendored `herdr` skill.
You are watching many agents at once. The skill is reading herdr's rolled-up state correctly, trusting it where it is authoritative, and knowing when (and how) to distrust it. This is judgment, not syntax — for exact commands, defer to the live CLI and the vendored herdr skill.
First check HERDR_ENV=1. If unset, you are not inside herdr and cannot inspect its panes; say so and stop.
blocked from working.Not this skill: organizing workspaces/tabs/panes or reattaching after restart (→ workspace-management); authoring the TOML detection rules themselves (→ herdr-configuration); raw command flags (→ vendored herdr skill).
herdr exposes one public field, agent_status, per pane:
done. So done is a personal to-do marker, not a durable property of the agent.The other public surface is the pane object and a subscribable status-change event stream (use it to drive a long-lived monitor instead of polling). Confirm the exact event/method name live in /docs/socket-api/ — do not hardcode it.
Before you trust a state, ask: does this agent's integration report lifecycle STATE for this pane? That, not "does it have a plugin/hook," is the dividing line.
Authority A — lifecycle-state hooks. Some agents (e.g. Pi, OpenCode) ship integrations that push their own idle/working/blocked transitions. When installed and actively reporting for the running pane, the integration is the sole authority — herdr does not second-guess it with screen reading. Trust these states directly.
Authority B — screen-manifest detection. Everything else. herdr reads the live bottom of the pane buffer and evaluates TOML rules (terminal title, progress sequences, screen patterns) against it. State is inferred from what is on screen now.
The trap: identity hooks are not state hooks. Several agents — Claude Code is the canonical case, also Codex and GitHub Copilot CLI — install hooks that report session identity (so sessions can be restored), but NOT lifecycle state. They look integrated, yet their idle/working/blocked still comes entirely from screen-manifest detection. Treat them as Authority B. Do not assume "Claude Code has a hook, therefore its state is authoritative."
To classify a specific agent, don't rely on a memorized roster (it rots): check /docs/integrations/, or run herdr agent explain on the pane and read what it reports as the manifest/detection source.
Why the category matters for blocked: blocked detection is deliberately strict for Authority-B agents. herdr only marks blocked when the live bottom-buffer snapshot matches a known visible approval/question/permission UI. If nothing matches, it falls back to idle — never a guessed blocked. Consequence: an Authority-B agent waiting at a novel or unrecognized prompt can read idle while it is actually stuck. For Authority-A agents this gap doesn't exist; the hook reports blocked directly.
State propagates up the tree, so the sidebar lets you triage without opening panes:
Read the tree top-down: a blocked workspace tells you where to look before you open anything.
agent_status (live CLI; the vendored skill has exact syntax). You want the status column across all panes/workspaces.blocked first (human needed) → done (review the result) → unknown (detection failed, investigate) → working (let it run) → idle (usually fine, but see the gotcha below).done marker.done) — see the vendored skill for the exact herdr wait / herdr agent wait syntax.Entry point: herdr agent explain <target> (add --json for machine output; it can also evaluate a captured screen offline against a named agent). Use it to see herdr's reasoning: the detected state, which manifest/source and version produced it, which rules matched, and the evidence flags. Confirm the exact flags with herdr agent explain --help.
Diagnose in this order:
herdr agent explain on the pane. Does the reported manifest source match the agent you think is running? If herdr is matching the wrong agent (or tmux), the state is being read against the wrong rules.idle until detection rules learn the pattern, and strict blocked-detection won't upgrade it. Read the live pane to confirm it's actually waiting. The fix is a detection rule → herdr-configuration skill.tmux, not the agent. herdr does NOT inspect tmux sessions launched inside a pane; it sees tmux as the foreground process, so the agent inside is invisible to detection. Run the agent directly in a herdr pane instead of nesting tmux.Full failure taxonomy and the authority table: references/gotchas.md and references/detection-and-triage.md.
herdr wait agent-status, herdr agent ... flags, the agent_status field schema) → vendored herdr skill (skills/herdr-agent-skill/SKILL.md) and herdr --help. Confirm live; do not memorize flags from this skill.herdr-configuration skill.npx claudepluginhub jbaham2/herdr-plugin --plugin herdrGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.