Known Limitations & Workarounds
Relevant source files
The following files were used as context for generating this wiki page:
PlanQueue is designed as a lightweight extension for the Oh My Pi (OMP) ecosystem, transforming session notes into a structured FIFO prompt queue. While it provides a robust mechanism for managing multi-step agent interactions, certain architectural constraints of the host environment and the terminal interface impose limitations on its functionality.
This page documents known technical boundaries, environmental restrictions, and the specific workarounds implemented to maintain a seamless user experience. These range from terminal escape sequence limitations to OMP session-handling caps.
Session Continuity and Chain Caps
The OMP host environment imposes a built-in limit on continuation chains, which directly affects how many prompts PlanQueue can automatically drain before requiring manual intervention.
Continuation Cap Limit
OMP restricts continuation chains to a maximum of 8 steps (SESSION_STOP_CONTINUATION_CAP). In a standard auto-run scenario, this means a queue with more than 8 consecutive lines will automatically pause after the 8th line is processed, even if no human-in-the-loop (HITL) barriers are present.
Workaround: HITL Barriers
To manage longer queues effectively, users should utilize --- barriers. These barriers serve as explicit checkpoints where the queue pauses for review. By placing a barrier before the 8th line, users can reset the chain state and resume the queue manually using the configured queueStep shortcut (default Ctrl+↓).
Sources: README.md:79-81, CHANGELOG.md:21-23
Terminal and UI Constraints
Because PlanQueue operates within a terminal-based UI (TUI) provided by OMP, it is subject to the limitations of terminal input handling and display.
Shortcut Key Conflicts
Some terminal emulators do not emit distinct escape sequences for complex modifiers like Ctrl+Shift+↓. This can prevent the default queueToggleAuto shortcut from functioning as expected.
Workaround: Users can rebind shortcuts via the global ~/.planqueue/config.json file. For example, rebinding queueToggleAuto to a simpler combination like ctrl+b ensures functionality in more restrictive terminal environments.
| Configuration Key | Default Value | Purpose |
|---|---|---|
editNotes | ctrl+n | Opens the note editor |
queueStep | ctrl+down | Dispatches the next pending task |
queueToggleAuto | ctrl+shift+down | Toggles the auto-run mode |
Sources: README.md:104-124, src/main.ts:182-195
Clipboard and Text Interaction
PlanQueue lacks a standard text-selection model common in GUI applications. Ctrl+C is reserved by the OMP host for other functions.
Workaround: The extension provides Alt+Shift+C to copy the entire note buffer. This uses the OSC 52 escape sequence, allowing clipboard synchronization to work even over SSH sessions, provided the terminal emulator supports it.
Sources: README.md:96-102, src/main.ts:51-59
Queue State Synchronization
The interaction between the note editor and the auto-run controller requires careful synchronization to prevent data loss or state corruption.
Editor-Auto-Run Conflict
If a user is editing the note while auto-run is actively processing tasks, there is a risk that a manual save could overwrite the progress markers (e.g., changing - [>] back to - [ ]).
Workaround: The system tracks the editorOpen state. While the editor is active, the auto-advance logic in the queue controller is suppressed. Additionally, any discarded drafts are appended to a .history.md file so that typed work is never permanently lost.
Sources: src/queue-controller.ts:167-168, src/main.ts:133-145
External Environment Integration
PlanQueue's behavior changes based on the environment it detects, specifically when running inside a "Herdr" workspace.
Workspace Notifications
When HERDR_ENV=1 is detected, the extension attempts to ping herdr notification show at every barrier. This is a "best-effort" integration; if the herdr command is missing or an older version is present, the subprocess call might fail.
Workaround: The extension wraps these calls in try-catch blocks and uses a timeout (2000ms) to ensure that a hanging notification call never blocks the main agent session.
Sources: src/queue-controller.ts:40-57, SECURITY.md:31-33
Summary of Technical Constraints
| Limitation | Scope | Mitigation |
|---|---|---|
| 8-Prompt Chain Cap | Architectural (OMP) | Use --- barriers to manual-reset. |
| Terminal Key Sequences | Environment (TUI) | Rebind keys in config.json. |
| No Text Selection | UI | Use Alt+Shift+C for OSC 52 copy. |
| Concurrent Edit/Auto | Logic | editorOpen lock and history files. |
| Missing Herdr Command | Subprocess | Try-catch and 2s timeout logic. |
Sources: README.md:79-81, src/queue-controller.ts:40-57, src/main.ts:133-145
PlanQueue effectively bridges the gap between manual prompt entry and full automation by providing specific workarounds for terminal and host-level limitations, ensuring that the user remains in control even when automation limits are reached.