herdr-zcode

A Herdr plugin that adds ZCode (zcode CLI, a.k.a. zcode-app-cli) agent support: panes running zcode show up in the sidebar as agents with live working / blocked / idle state, and sessions can be reattached after a Herdr restart.

Herdr cannot recognize zcode by itself — it is not in Herdr's built-in agent list. Instead, this plugin uses Herdr's official self-reporting API (add-herdr-support): it registers lifecycle hooks in zcode's settings file (~/.zcode/cli/setting.json) that report pane state to Herdr as zcode runs. Outside Herdr panes the hooks are no-ops.

Requirements

Requirement	Version	Why
Herdr	0.9.2+	session reattach (--resume argv) needs 0.9.2+; older versions ignore it
zcode-app-cli	latest	the zcode CLI this plugin integrates with; zcode must be on PATH
Node.js	22.19+	same runtime zcode-app-cli already requires — the plugin scripts are dependency-free Node

Works on macOS, Linux and Windows.

Install

herdr plugin install ichadhr/herdr-zcode

The repo is tagged herdr-plugin, so it also appears in Herdr's plugin marketplace index.

Local development:

herdr plugin link /path/to/herdr-zcode

What it does

• On startup (and via the Install ZCode integration hooks action): keeps a copy of the reporter script in the plugin's config dir and registers it on all zcode hook events (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop) in ~/.zcode/cli/setting.json. Idempotent — safe to run repeatedly, replaces older copies of the same integration.
• State mapping: prompt submit / tool start / tool end → working; permission request → blocked; turn stop / session start → idle.
• Session restore: SessionStart reports zcode --resume <session-id> so Herdr can reattach to the right session (requires Herdr 0.9.2+).
• Remove ZCode integration hooks action unregisters everything.

Verify

herdr plugin action invoke herdr-zcode.status

Then start zcode in a Herdr pane and submit a prompt — the pane appears as a zcode agent in the sidebar. State only updates after zcode sessions restart (hooks load at process startup).

Notes

• The self-report source id is zcode-herdr (Herdr reserves the herdr: prefix for its built-in integrations).
• Detection manifests are intentionally not shipped: Herdr only loads manifests for agent ids it already knows, so self-reporting is the supported path.
• "ZCode" here means the community terminal client kingsword09/zcode-cli (npm install -g zcode-app-cli). Compatibility with other zcode distributions depends on them sharing the same hook events (hooks.events.* in ~/.zcode/cli/setting.json) and settings path.
• Plugins run unsandboxed with full CLI access. Review scripts/manage_hooks.js and hooks/herdr_agent_state.js — they only touch the zcode settings file and call herdr pane report-agent*.