---

name: shepherd description: "Inspect the status, progress, latest messages, compact structured history, and recent tool results of coding agents managed by Herdr using Shepherd. Use whenever the user asks what another Herdr-managed coding agent is doing, whether it is working, blocked, idle, or done, what it recently reported or changed, or needs structured context before coordinating with that agent. Also use outside Herdr when the user provides an explicit Herdr workspace or session scope for agent inspection." compatibility: "Requires the Shepherd CLI and daemon. Current-workspace lookup requires HERDR_ENV=1 and HERDR_WORKSPACE_ID. Explicit Shepherd workspace or session scopes work outside Herdr."

Shepherd agent inspection

Use Shepherd for structured coding-agent status, compact message history, and recent compact tool results. Use the official herdr skill for live workspace, tab, pane, terminal input/output, focus, spawn, and wait operations.

Ensure the daemon is running

Check the daemon before the first Shepherd query:

shepherd daemon status

If the JSON response has state: "stopped", start it once:

shepherd daemon start

Do not restart or stop a running daemon unless the user asks.

Select the scope

Use the current workspace only when both HERDR_ENV=1 and HERDR_WORKSPACE_ID are set:

shepherd agent list --json

If either value is missing, do not guess the workspace or fall back to --all. Ask for an explicit scope.

Outside Herdr, or when the user names a scope, pass it explicitly:

shepherd agent list --workspace <workspace-id> --json
shepherd agent list --all --json

Use --session <name> when workspace ids or agent targets are ambiguous across running Herdr sessions.

Inspect an agent

Start with agent list. Each row contains an optional Herdr live name, such as reviewer, and a runtime agent kind, such as codex. Shepherd resolves an exact pane id, terminal id, or Shepherd agent id first; an exact live name second; and a unique runtime kind only as a fallback. Use an exact pane id or terminal id when the caller has already selected a row. Otherwise use its live name when present. Do not call agent list repeatedly in a polling loop, and inspect updatedAt when freshness matters.

Use agent get or agent read for explicit current detail after selecting the exact target.

shepherd agent get <target> --json
shepherd agent read <target> --limit 20 --json

Add the same --workspace and --session scope used for agent list when operating outside the current Herdr workspace.

agent get returns metadata, status, compact history, and the latest compact tool result. agent read returns recent user, assistant, and compact tool_result messages; it does not return raw full terminal output.

Agent status uses working, blocked, idle, done, or unknown. done means the agent finished and its pane has not yet been viewed.

Coordinate through the official Herdr skill

When a task also requires live terminal output, pane control, input, spawning, focus, or waiting, load and follow the installed official herdr skill as the source of truth:

https://github.com/ogulcancelik/herdr/blob/master/SKILL.md

If that skill is unavailable, stop the Herdr-control portion and ask the user to install it:

npx skills add ogulcancelik/herdr --skill herdr -g

Do not copy or guess Herdr CLI commands in this skill.

Boundaries

• Shepherd returns agents from running Herdr sessions only.
• Use Shepherd for structured semantic history, not raw terminal fidelity.
• Shepherd does not start, prompt, wait for, focus, or send terminal input to agents.
• Use the official herdr skill for live terminal state and control.