Lesson 02 · Using Herdr Effectively

The Attention Queue

Use agent state to decide where to look, then verify before you act

Your tangible win

After this lesson, you can look at a multi-agent Herdr session and answer three questions: which agent needs me, what does Herdr actually know, and what should I verify before responding?

The operating model

Herdr reduces polling, not judgment. It surfaces the pane most likely to need attention. You still inspect the terminal and decide whether an approval or answer is safe.

State rolls upward

Herdr detects agents inside panes and rolls their state up through the tab and workspace. That lets you scan projects instead of opening every terminal manually.

flowchart TB A["Agent"] --> P["Pane"] --> T["Tab"] --> W["Workspace"] style A fill:#fef9c3,stroke:#ca8a04,stroke-width:2px style P fill:#f0fdf4,stroke:#16a34a,stroke-width:2px style T fill:#dbeafe,stroke:#2563eb,stroke-width:2px style W fill:#faf5ff,stroke:#9333ea,stroke-width:2px

Figure 1: A blocked agent makes its pane, tab, and workspace look blocked; a working agent makes its workspace active.

State	Meaning	Your response
`working`	The agent is actively running.	Let it work; monitor if needed.
`blocked`	It needs input, approval, or a decision.	Inspect the pane before answering.
`done`	It finished and you have not viewed it yet.	Review its output.
`idle`	It is finished or waiting and has been seen.	It is ready for a new task.
`unknown`	Herdr cannot classify it confidently.	Read the pane manually.

The authority question

“Herdr sees an agent” and “Herdr knows the exact lifecycle state” are different claims. The source of truth depends on the agent and its installed integration.

flowchart TB P2["Foreground process"] --> S["Screen manifest"] --> R["Reported state"] P2 --> I["Lifecycle integration"] --> R style P2 fill:#dbeafe,stroke:#2563eb,stroke-width:2px style S fill:#f0fdf4,stroke:#16a34a,stroke-width:2px style I fill:#faf5ff,stroke:#9333ea,stroke-width:2px style R fill:#fef9c3,stroke:#ca8a04,stroke-width:2px

Figure 2: Screen detection and integrations are different evidence paths. A complete lifecycle integration can become authoritative; a session-only integration helps restore identity but does not replace state detection.

Screen detection

For agents without a complete lifecycle authority, Herdr identifies the foreground process and reads the live bottom buffer of the pane. It matches the visible agent UI against a detection manifest. Scrolling back does not change what Herdr detects.

Lifecycle integration

Some agents can report their lifecycle directly through hooks or plugins. When that integration is installed and actively reporting, it authors working, idle, and blocked for that pane. Herdr does not run competing screen fallback for that same lifecycle authority.

Session-only integration

Other integrations provide a native session reference so Herdr can restore an agent after a server restart. Their hooks may not cover every approval, cancellation, or interrupt, so Herdr continues to use screen detection for state.

Safety rule

A blocked state is a routing hint: “look here.” It is not an approval. A new or unusual prompt may even appear as idle when no manifest rule matches, so unusual states require inspection rather than automation.

Diagnose a surprising state

Start with the agent list:

herdr agent list

Then inspect the integration status:

herdr integration status

If one agent looks wrong, ask the running server to explain its classification:

herdr agent explain <target>

For scripts and bug reports, use JSON:

herdr agent explain <target> --json

The explanation can show the final state, manifest source and version, matched rule, evidence, fallback reason, local override shadowing, and remote update status. For a saved fixture, use:

herdr agent explain --file screen.txt --agent codex --json

Keep detection current

Herdr checks for remote manifest updates automatically by default. To fetch and activate updates immediately:

herdr server update-agent-manifests

After manually editing a local override under ~/.config/herdr/agent-detection/, reload it:

herdr server reload-agent-manifests

Local overrides win over remote and bundled manifests. Invalid overrides are ignored and Herdr falls back to a valid cached or bundled manifest.

Install the right integration

Install the integration for the agent you actually use, not every integration listed in the docs:

herdr integration install claude
herdr integration status

For Claude Code, the integration adds native session identity for restore; Herdr still uses screen detection for lifecycle state. Other agents have different roles. Check the official integration table before assuming an install changes state authority.

Checkpoint: make a decision from the queue

Open a Herdr session containing at least one agent.
Run herdr agent list.
Choose the agent with the most urgent state, especially blocked.
Run herdr agent explain <target> --json.
Read the pane before sending any approval or answer.
Record whether the state was trustworthy, ambiguous, or wrong.

An agent is marked blocked. What is the correct next move?

Remember this

Herdr is an attention router. State tells you where to look; the pane tells you what is happening; your judgment decides what happens next.

Primary sources

This lesson follows Herdr's official Agents, Integrations, and CLI Reference. Use the attention queue cheat sheet for retrieval practice.