Introduction to PlanQueue

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/main.ts
• src/queue-controller.ts
• CHANGELOG.md
• SECURITY.md
• CONTRIBUTING.md
• package.json

PlanQueue is an extension for the Oh My Pi (OMP) coding agent harness that facilitates structured, multi-step planning by transforming session notes into a First-In-First-Out (FIFO) prompt queue. It renders a dedicated panel below the agent's status line, allowing users to write complex plans as Markdown lists and dispatch them sequentially to the agent. This approach eliminates the need for manual copy-pasting of repetitive prompts and provides visual feedback on task progress directly within the terminal interface.

Sources: README.md:1-12, package.json:3-5

The system persists notes on a per-repository, per-branch, and per-session basis, ensuring that context remains relevant to the current workspace. It features manual stepping, human-in-the-loop barriers, and an "auto-run" mode that feeds prompts to the agent as soon as the previous turn settles. Additionally, it provides LLM-accessible tools that allow the agent to modify the queue itself, creating a collaborative planning environment between the user and the AI.

Sources: CHANGELOG.md:13-26, src/main.ts:13-20

System Architecture

PlanQueue is built as a TypeScript extension running on the Bun runtime. It integrates with the OMP Extension API to manage UI components, register commands, and interact with the agent's message flow.

Component Overview

The architecture consists of a main entry point that wires OMP-specific logic to a core set of utilities, and a queue controller that manages the state of the active prompt queue.

Component	Description
Main Factory (src/main.ts)	Bootstraps the extension, handles session lifecycle events, and registers UI widgets/commands.
Queue Controller (src/queue-controller.ts)	Manages the logic for manual/auto-stepping, human-in-the-loop barriers, and auto-run state.
Core Logic (@aryrabelo/planqueue-core)	External dependency containing pure logic for Markdown parsing, path resolution, and state normalization.
UI Widget	A HUD component placed belowEditor that renders the current queue state using glyphs.
Custom Editor	A multi-line Markdown editor for the session note, accessible via shortcuts or commands.

Sources: src/main.ts:13-60, src/queue-controller.ts:10-25, package.json:52-54

Data Flow: Dispatching a Prompt

When a user triggers a queue step, the system identifies the next pending task in the Markdown note, updates its visual state, and sends it to the OMP agent.

Queue States and Glyphs

The session note is parsed as a Markdown list where specific checkbox markers represent the state of each prompt. Plain lines and - bullets are automatically normalized to pending tasks upon saving.

Marker	State	Glyph	Description
- [ ]	Pending	☐	Task is waiting to be dispatched.
- [>]	In-flight	▸	Task has been sent and the agent is currently processing it.
- [x]	Done	✓	Task turn has settled successfully.
---	Barrier	N/A	Human-in-the-loop checkpoint that pauses auto-run.

Sources: CHANGELOG.md:16-18, README.md:46-55, src/main.ts:145-155

Automation and Logic

Auto-Run Mode

Auto-run (Ctrl+Shift+Down) automates the queue by feeding the next prompt as soon as the agent becomes idle. If a turn ends in an error or is aborted, auto-run automatically halts to prevent the agent from proceeding with a broken session.

Sources: src/queue-controller.ts:168-196, CHANGELOG.md:21-23

Human-in-the-Loop Barriers

Barriers are defined by a line containing three or more dashes (---). When the queue reaches a barrier:

1. Auto-run is disabled.
2. A notification is sent (including a herdr ping if in a Herdr environment).
3. The user must manually "step" to delete the barrier and resume the queue.

Sources: src/queue-controller.ts:105-112, README.md:57-61

Storage and Persistence

PlanQueue stores data in a structured directory hierarchy within the user's home directory.

Legacy Fallback

The system maintains a read-only fallback chain for users migrating from earlier versions. It searches for notes in the following order:

1. ~/.planqueue/ (New standard)
2. ~/.free-text/ (Legacy)
3. ~/.omp-free-text/ (Legacy)

Sources: src/main.ts:100-110, tests/core-integration.test.ts:15-25

Agent Interaction (Tools)

PlanQueue exposes two primary tools to the LLM agent, enabling it to manage the user's plan programmatically.

note_add

Appends a single task to the bottom of the current note.

• Parameters: text (string)
• Use Case: "Remember to update the README later."
  Sources: src/main.ts:173-206

make_note

Writes a full, decomposed plan to the note, including optional headings and barriers.

• Parameters: heading (optional string), steps (array of objects containing prompt, details, and barrierAfter).
• Use Case: Decomposing a high-level goal into a multi-step prompt queue.
  Sources: src/main.ts:223-288

Configuration

Global configuration is stored in ~/.planqueue/config.json. This allows users to override default keybindings, which is particularly useful for terminal environments that do not support certain key combinations.

{
  "shortcuts": {
    "editNotes": "ctrl+n",
    "queueStep": "ctrl+down",
    "queueToggleAuto": "ctrl+shift+down"
  }
}

Sources: README.md:80-90, src/main.ts:159-171

Conclusion

PlanQueue transforms the OMP session note from a passive text buffer into an active control mechanism for coding agents. By combining structured Markdown parsing with automated queueing logic and LLM-integrated tools, it provides a robust framework for managing complex, multi-turn AI workflows without losing track of the overarching plan.