Configuration & Shortcuts
Relevant source files
The following files were used as context for generating this wiki page:
PlanQueue utilizes a global configuration system and customizable keyboard shortcuts to manage the flow of prompt queues within OMP (Oh My Pi). The system is designed to provide a seamless "Human-in-the-loop" experience, allowing users to either manually step through tasks or automate the queue drainage.
Configuration is centralized in a global JSON file, while shortcuts are registered through the OMP Extension API to interact with the internal QueueController. This setup ensures that user preferences persist across different repositories and branches while maintaining a consistent interface for managing coding agent tasks.
Sources: README.md:10-18, src/main.ts:16-24
Configuration System
PlanQueue stores its global configuration and session data in the user's home directory. Unlike session notes, which are organized by repository and branch, the shortcut configuration is global.
Global Configuration File
The system reads settings from ~/.planqueue/config.json. If this file is missing or contains malformed entries, the extension falls back to hardcoded defaults and logs a warning to the OMP logger.
Sources: README.md:120-130, src/main.ts:186-200, SECURITY.md:27-30
Configuration Data Model
The configuration primarily focuses on ShortcutConfig, which maps internal actions to physical key combinations.
| Field | Type | Description | Default Value |
|---|---|---|---|
editNotes | string | Key combo to open the multi-line note editor. | ctrl+n |
queueStep | string | Key combo to send the next prompt or pass a barrier. | ctrl+down |
queueToggleAuto | string | Key combo to toggle the auto-run mode for the queue. | ctrl+shift+down |
Sources: README.md:110-117, src/main.ts:198-200
Configuration Loading Flow
The following diagram illustrates how PlanQueue initializes shortcuts during startup.
The system also includes a read-only fallback mechanism for legacy configuration paths (~/.free-text/ and ~/.omp-free-text/) to ensure backward compatibility for long-time users.
Sources: src/main.ts:186-201, CHANGELOG.md:46-47
Keyboard Shortcuts
Shortcuts are the primary method of interacting with the PlanQueue prompt queue. They are registered using the OMP pi.registerShortcut API and are bound to specific handlers in src/main.ts and src/queue-controller.ts.
Shortcut Actions
- Edit Notes (
editNotes): Opens a custom editor overlay. Enter saves the content, while Esc handles closing with unsaved change prompts. - Queue Step (
queueStep):- If the current line is a prompt (
- [ ]), it sends the message to the agent and marks it as in-flight (- [>]). - If the current line is a barrier (
---), it deletes the barrier to allow the queue to proceed.
- If the current line is a prompt (
- Toggle Auto-Run (
queueToggleAuto): Switches theautostate of theQueueController. When enabled, the queue automatically sends the next prompt whenever the agent settles (idle state).
Sources: README.md:58-85, src/queue-controller.ts:121-177
Shortcut Integration Logic
The QueueController manages the state transitions triggered by shortcuts.
Shortcut Customization Syntax
Shortcuts must follow the OMP KeyId syntax, which uses lowercase modifiers and keys separated by plus signs.
- Supported Modifiers:
ctrl,shift,alt,super. - Example:
"alt+enter","ctrl+b". - Note: Customizing shortcuts is particularly useful for terminal environments that do not correctly emit certain combinations, such as
Ctrl+Shift+Down.
Sources: README.md:115-119, src/main.ts:197-200
Visual Indicators (Widget Hints)
The status of shortcuts and the queue mode is reflected in the UI widget located below the editor. The queueHint function generates a dynamic string showing the current keybindings and their status.
| Mode | Visual Indicator | Meaning |
|---|---|---|
| Normal | (Ctrl+N · Ctrl+↓ queue) | Default manual mode hints. |
| Auto-Run | ... Ctrl+Shift+↓ auto ▶ | Indicates auto-run is active. |
| Blocked | (Ctrl+↓ to pass) | Appears when the queue is paused at a --- barrier. |
Sources: README.md:52-56, src/queue-controller.ts:98-112, src/main.ts:213-228
Summary
Configuration in PlanQueue is designed for simplicity and persistence, using a global JSON file to manage shortcut preferences. By decoupling the queue logic from the physical keybindings, PlanQueue allows users to adapt the tool to their specific terminal capabilities while providing clear visual feedback through a dynamic widget. This system ensures that the "write once, run as a queue" philosophy is maintained regardless of the user's local environment.
Sources: README.md:12-18, src/main.ts:186-205