Herdr Environment Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Herdr Environment Integration is a specialized feature set within PlanQueue designed to enhance the developer experience when running in a Herdr-enabled workspace. It provides proactive notifications and state synchronization between the PlanQueue prompt queue and the Herdr environment, specifically focusing on human-in-the-loop (HITL) checkpoints.
When the extension detects it is running within Herdr (via the HERDR_ENV=1 environment variable), it enables specific behaviors such as desktop-level notifications during Auto-run and synchronization of "blocked" states to the Herdr sidebar. This integration ensures that developers are alerted when the agent requires manual review or when a task queue hits a pre-defined barrier.
Sources: README.md:65-67, src/queue-controller.ts:40-42
Environment Detection and Triggering
The integration is conditionally activated based on the presence of the HERDR_ENV environment variable. PlanQueue checks this variable to determine whether to execute Herdr-specific logic, such as shelling out to the herdr CLI or emitting internal events.
The integration triggers specific side effects only when the environment variable is explicitly set to "1".
Sources: src/queue-controller.ts:41, SECURITY.md:27-29
Auto-run Notifications
During an auto-run sequence (Ctrl+Shift+↓), PlanQueue feeds queued tasks to the agent one by one. When a human-in-the-loop barrier (---) is encountered, the integration triggers a system-level notification via the Herdr CLI.
The Notification Mechanism
The extension uses pi.exec to call the herdr command-line utility. This is a best-effort operation; if the Herdr CLI is missing or returns an error, PlanQueue swallows the failure to prevent disrupting the active OMP session.
| Parameter | Value / Source | Description |
|---|---|---|
| Command | herdr | The Herdr CLI entry point. |
| Subcommand | notification show | Displays a workspace-level alert. |
| Title | "Queue paused - your turn" | The primary notification text. |
--body | label (e.g., repo/branch) | Contextual information about the origin of the pause. |
--sound | request | Auditory cue for the developer. |
Sources: src/queue-controller.ts:43-55, CHANGELOG.md:32-34
Blocked State Synchronization
The integration maintains a "blocked" state that synchronizes PlanQueue's status with the Herdr workspace sidebar. This is primarily used to indicate when the queue is waiting for human intervention at a barrier.
Event Emission
When the queue enters or leaves a blocked state, PlanQueue emits a herdr:blocked event through the OMP event bus. This allows the Herdr environment to update its UI (such as a sidebar) to reflect the agent's status.
The state synchronization uses a strictly-paired event pattern to ensure the Herdr UI accurately reflects the blocked status of the prompt queue.
Sources: src/queue-controller.ts:77-90
Implementation Details
The core logic for the Herdr integration resides in the QueueController.
Logic for Barrier Handling
When a barrier is encountered in auto-run mode, the haltAtBarrier function is invoked. This function performs the following steps in sequence:
- Disables
automode. - Calls
setBlocked(true, label), which emits theherdr:blockedevent. - Refreshes the OMP widget UI.
- Notifies the user via standard OMP notification.
- Invokes
pingHerdrto trigger the CLI notification.
Sources: src/queue-controller.ts:109-119
Security and Scope
The Herdr integration is strictly scoped to specific interactions. The extension only spawns the herdr notification show subprocess and does not execute arbitrary commands or access network resources via Herdr.
Sources: SECURITY.md:27-29
The Herdr Environment Integration provides a bridge between the terminal-based PlanQueue and the broader developer workspace, ensuring that automated prompt sequences are safely governed by human review through multi-channel notifications and status visibility.