Prompt Queue Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Prompt Queue Engine is the core logic within PlanQueue that transforms Markdown-based session notes into a First-In-First-Out (FIFO) execution pipeline for coding agents. It enables developers to plan multi-step operations upfront as a list of prompts, which are then dispatched sequentially to an agent either through manual triggers or an automated "auto-run" mode.
This engine handles the parsing of task states, the management of human-in-the-loop barriers, and the coordination between the user interface and the underlying AI agent. By persisting notes per repository and branch, it ensures that long-running plans remain consistent across different coding sessions.
Sources: README.md:9-13, src/main.ts:1-12, src/queue-controller.ts:1-12
Core Architecture and Data Flow
The engine operates by treating a Markdown file as a state machine where each line represents a task, a barrier, or metadata. The queue-controller.ts acts as the primary orchestrator, interfacing with the @oh-my-pi/pi-coding-agent SDK to send messages and react to session lifecycle events.
The Note as a Queue
The queue is derived directly from the note content. Task states are managed through specific Markdown checkbox markers:
- [ ]: Pending task.- [>]: In-flight task (currently being processed by the agent).- [x]: Done task (successfully completed).---: Barrier (Human-in-the-loop checkpoint).
Sources: CHANGELOG.md:15-18, src/queue-controller.ts:10-15, tests/core-integration.test.ts:27
Logic Flow Diagram
The following diagram illustrates how a prompt moves from a pending state in the note to execution by the agent.
Queue Control Mechanisms
The engine provides two primary modes of operation: Manual Stepping and Auto-run.
Manual Stepping
Triggered via Ctrl+↓ (default), this mechanism dispatches the immediate "head" of the queue. If the head is a prompt, it is sent to the agent. If the head is a --- barrier, the barrier is removed, effectively "unlocking" the next item for the subsequent trigger.
Sources: src/queue-controller.ts:101-120, README.md:46-50
Auto-run and Session Synchronization
Auto-run, toggled by Ctrl+Shift+↓, automatically feeds the next prompt whenever the agent finishes its current task (detected via the session_stop event).
- Failure Handling: Auto-run automatically halts if a turn ends in an
erroror isabortedto prevent the agent from proceeding with a corrupted session state. - Continuation Logic: Lines indented under a task are treated as "continuation lines" and sent as a single multi-line prompt to maintain context.
- Barriers: Auto-run will always pause at a
---line, requiring manual intervention to proceed.
Sources: src/queue-controller.ts:31-40, src/queue-controller.ts:143-160, CHANGELOG.md:22-25
Component Interactions
The engine is highly integrated with the OMP (Oh My Pi) environment and external tools like Herdr.
API and External Integration Table
| Interaction | Description | Source |
|---|---|---|
pi.sendUserMessage | The primary method used to dispatch prompts to the AI agent. | src/queue-controller.ts:83 |
note_add Tool | An LLM tool allowing the agent to append new - [ ] tasks to the queue. | src/main.ts:252-282 |
make_note Tool | An LLM tool for decomposing high-level goals into multi-step prompt plans. | src/main.ts:303-369 |
| Herdr Notification | Pings herdr notification show when a barrier is reached if HERDR_ENV=1. | src/queue-controller.ts:43-62 |
| OSC 52 | Used to copy the entire note buffer to the system clipboard via terminal escape sequences. | src/main.ts:68-75 |
Sequence of Automated Execution
This sequence diagram shows the interaction between the Engine, the Agent, and the History log during an auto-run cycle.
Configuration and Shortcuts
The engine's behavior can be customized via a global configuration file located at ~/.planqueue/config.json.
| Shortcut Key | Default | Function |
|---|---|---|
editNotes | ctrl+n | Opens the multi-line Markdown editor overlay. |
queueStep | ctrl+down | Dispatches the next prompt or removes a barrier. |
queueToggleAuto | ctrl+shift+down | Toggles the automated drain of the prompt queue. |
Sources: src/main.ts:511-526, README.md:111-125
The engine follows a strict persistence hierarchy, storing notes in ~/.planqueue/{repo}/{branch}/{session-id}.md while maintaining a legacy read-only fallback to ~/.free-text/ and ~/.omp-free-text/ for backward compatibility.
Sources: src/main.ts:446-460, CHANGELOG.md:33-35
Summary
The Prompt Queue Engine serves as the operational heart of PlanQueue, bridging the gap between static planning and active AI agent execution. By leveraging a simple Markdown-based state tracking system and integrating deeply with session lifecycle events, it allows for both granular manual control and efficient automated multi-step workflows. Its reliance on local persistence and standardized tools like OSC 52 and Herdr ensures a robust experience for developers working in diverse terminal environments.