herdr

Recipe card from the charly-automation plugin (Commands — runtime CLI verbs).

herdr

The compiled-in ‘charly herdr’ CLI + the declarative herdr: check verb for a Herdr terminal-multiplexer session — a command:herdr + verb:herdr plugin. The plugin speaks the herdr NDJSON socket API directly: no upstream ‘herdr’ binary, no SDK (the wire contract is herdr api schema --json, protocol 20).

Session targeting (safety boundary, as code)

The focused Herdr session is OFF-LIMITS from outside. The plugin targets:

• --session <name> — a named test session (~/.config/herdr/sessions/<name>/herdr.sock), the sanctioned isolated server for experiments.
• --endpoint <host:port> — a TCP endpoint speaking the herdr NDJSON protocol (the pod-herdr socket bridge on port 8095, host-resolved for verbs).
• HERDR_SOCKET_PATH — an explicit socket path.
• HERDR_ENV=1 — you are INSIDE herdr (a herdr pane); the current session is yours.
• --focused — explicit operator intent to touch the focused session.

With no target outside herdr, charly herdr errors with guidance — never silently inspects or mutates the focused session. Parse pane/workspace/tab IDs from command output; prefer non-disruptive operations; never server.stop an active session.

Command tree

• charly herdr status — ping + workspace/tab/pane/agent counts + focused ids.
• charly herdr session snapshot — the live session snapshot (JSON).
• charly herdr workspace list|create [--label] [--cwd] [--focus].
• charly herdr tab list [--workspace] | create [--workspace] [--label] [--focus].
• charly herdr pane list [--workspace] | split [--direction right|down] [--pane] [--cwd] [--focus].
• charly herdr pane run <pane> <command...> — send text + Enter.
• charly herdr pane read <pane> [--source visible|recent|recent-unwrapped|detection] [--lines N].
• charly herdr pane wait-output <pane> --match <text>|--regex <pattern> [--source] [--timeout-ms].
• charly herdr pane send-text | send-keys — raw literal/keys input.
• charly herdr agent list | get <target>.
• charly herdr agent wait <target> [--until idle|working|blocked|done|unknown] [--timeout-ms].
• charly herdr agent prompt <target> <text> [--wait] [--timeout-ms].
• charly herdr agent report <pane> <agent> --state <state> [--message] — wraps pane.report_agent (a custom agent reporting its own lifecycle, like the bed’s fake agent).
• charly herdr config — the resolved target + how it was chosen.

The herdr: check verb

Declarative venue-probe counterpart of the CLI, authored as a check: step in a candy/box plan. It resolves the in-venue herdr socket bridge (port 8095) to a host-routable address over the reverse channel and probes with the SAME client the CLI uses (R3). Methods:

• herdr: ping — the server answers.
• herdr: session-snapshot — workspace/tab/pane/agent summary.
• herdr: workspace-list, herdr: tab-list [workspace: w1], herdr: pane-list [workspace: w1].
• herdr: agent-list.
• herdr: pane-wait-output [pane: w1:p1] [match: text|regex: pattern] [source] [timeout].
• herdr: agent-wait [agent: name] [until: idle|working|blocked|done|unknown] [timeout].
• herdr: agent-prompt [agent: name] [text: ...] [timeout].

The verb skips under charly check box (no live venue on a disposable podman run --rm).

Cross-References

• /charly-automation:herdr-box — the herdr stack box + check-herdr-pod bed (pod-herdr repo).
• /charly-internals:plugin — compiled-in command plugins, the provider model.
• The herdr agent skill (herdrdev/herdr v0.8.2 skills/herdr/SKILL.md) — the upstream agent contract this plugin operationalizes.