When an Agent Status Freezes in a Herdr Pane, Where Do You Look?

When a Herdr agent status looks frozen in the sidebar, start with herdr agent explain to see the detection snapshot, matched rule, and any idle fallback. Then separate client detach from server/session stop, and read the real terminal stream with agent read / pane read.

This guide covers only troubleshooting when pane or workspace status looks stuck or misclassified as idle. It is not an install walkthrough, review, or pricing note. Claims follow the official Herdr Agents and CLI docs.

Where do you look when the status does not change?

One-line answer: Run herdr agent explain <target> first for the final state, matched rule, and idle-fallback reason.

Herdr detects the foreground process in each pane, then assigns one status authority per pane. If a full lifecycle integration is installed and reporting, those hook reports own idle / working / blocked. Otherwise Herdr classifies against a live bottom-buffer screen snapshot using TOML manifests.

herdr agent explain <pane-or-agent>
herdr agent explain --verbose
herdr agent explain --json

Explain output includes the agent kind, final state, manifest source and version, matched rule evidence, reasons screen detection was skipped, and the idle fallback when no rule matched. For known agents with no match, Herdr falls back to idle as default_known_agent_idle_fallback. blocked is deliberately strict: it only applies when the visible bottom snapshot matches known approval, question, or permission UI.

Also check:

  • herdr agent list / herdr agent get — does the API state match the sidebar?
  • herdr integration status — reinstall with herdr integration install <agent> if outdated.
  • After editing a local override under ~/.config/herdr/agent-detection/, run herdr server reload-agent-manifests.
  • Sandbox wrappers that hide the real process may need HERDR_AGENT=<kind> on the wrapper command.

Screen detection follows the latest bottom buffer. If an alt-screen UI hides the approval prompt, or a custom manifest uses something like skip_state_update, the sidebar can diverge from reality—explain’s skip/fallback fields are the clue.

What is the difference between restart and detach?

One-line answer: Detaching the client leaves the server and pane agents running; stopping the server or session can tear those processes down.

Officially, Herdr’s server and agents keep running after you close or detach the client. From a direct agent attach, detach with ctrl+b q (literal ctrl+b is ctrl+b ctrl+b). herdr agent attach <name> attaches to one agent terminal instead of the full UI.

ActionEffect
Client detach / close UIServer, panes, and agents keep running; reattach with herdr
herdr session stopStops that session
herdr server stopStops the headless server; its pane processes may exit
herdr pane close / herdr workspace closeClears layout/workspace state (not a git worktree delete)
herdr server reload-configApplies reloadable settings without killing panes

Killing the server because the status “looks stuck” can also kill a healthy agent turn. Classify display error vs process death with explain/read before restarting.

Where do you read the logs?

One-line answer: Use herdr agent read / pane read for terminal output; use HERDR_LOG and herdr status (plus plugin logs) for Herdr itself.

herdr agent read <target> --source detection
herdr agent read <target> --source recent-unwrapped --lines 120
herdr pane read <pane_id> --source recent --lines 80

Official read sources:

  • visible — current rendered screen
  • recent / recent-unwrapped — recent scrollback (prefer unwrapped for logs)
  • detection — bottom-buffer snapshot used by screen detection

Set HERDR_LOG (for example HERDR_LOG=herdr=debug) for Herdr’s own filter. Use herdr status, herdr status server, and herdr status client for health. For plugins, herdr plugin log list shows action logs.

Order of operations: ① agent explain → ② detach vs server stop → ③ agent/pane read plus status/HERDR_LOG. Confirm the detection snapshot before restarting an agent from the sidebar alone.

Sources