Extension Architecture

Relevant source files

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

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

PlanQueue is an extension for the Oh My Pi (OMP) coding agent harness that implements a session-persistent notes panel and a FIFO prompt queue. The architecture is designed to allow developers to plan multi-step tasks as Markdown notes, which are then dispatched to the agent either manually or through an automated "auto-run" mechanism.

Sources: README.md:9-14, package.json:2-3

Core System Components

The extension's architecture is divided between OMP-specific wiring and core logic. While pure logic (paths, queue management, storage) is imported from @aryrabelo/planqueue-core, the extension itself manages the interaction with the OMP SDK, including UI components, keyboard shortcuts, and agent tool registration.

Component Overview

Component	Responsibility	File Reference
Main Entry (planQueueExtension)	Initializes the session, registers commands, tools, and shortcuts.	src/main.ts:285-450
Queue Controller	Manages the state of the prompt queue (manual/auto) and agent dispatch.	src/queue-controller.ts:77-227
Storage Layer	Handles local Markdown file I/O for notes and history.	src/main.ts:326-363
UI/Widget	Renders the visual status panel below the OMP editor.	src/main.ts:303-317
LLM Tools	Provides note_add and make_note for agent-driven note manipulation.	src/main.ts:161-262

Sources: src/main.ts:22-38, src/queue-controller.ts:15-22

Data Flow and State Management

PlanQueue utilizes the active Markdown note as the primary source of truth for the prompt queue. Task states are represented by Markdown checkbox glyphs: [ ] for pending, [>] for in-flight, and [x] for completed.

Queue Dispatch Logic

The following diagram illustrates how the queue-controller handles a manual or automated step in the prompt queue.

The system monitors session_stop events to transition tasks from in-flight to completed and, if auto-run is enabled, primes the next available task.

Sources: src/queue-controller.ts:25-33, src/queue-controller.ts:114-135, src/queue-controller.ts:200-205

Storage Architecture

Notes are persisted locally to the user's home directory. The architecture ensures that notes are isolated by repository, branch, and session ID.

Directory Structure

Files are organized under ~/.planqueue/:

• Active Notes: ~/.planqueue/{repo}/{branch}/{session-id}.md
• History: ~/.planqueue/{repo}/{branch}/{session-id}.history.md (Append-only record of every change)
• Configuration: ~/.planqueue/config.json

The extension also maintains read-only backward compatibility with legacy paths: ~/.free-text/ and ~/.omp-free-text/.

Sources: src/main.ts:339-342, README.md:79-84, SECURITY.md:26-29

Agent Integration (LLM Tools)

PlanQueue exposes two primary tools to the coding agent, allowing it to interact with the user's plan.

note_add Tool

Appends a single task line to the current note.

• Approval Mode: write
• Input: A text string containing the task.
• Logic: Uses appendTask from the core library to format the string as a Markdown checkbox.

make_note Tool

Allows the agent to decompose a high-level goal into a multi-step plan.

• Approval Mode: write
• Input: An optional heading and an array of steps (containing prompt, details, and barrier flags).
• Logic: Bootstraps or appends a structured prompt queue to the note.

Sources: src/main.ts:175-197, src/main.ts:219-253

Interaction and Input Flow

The extension manages three primary interaction methods: Slash commands, configurable keyboard shortcuts, and the custom notes editor.

Sequence: Opening the Notes Editor

Configuration and Customization

Shortcuts are loaded at startup from a global configuration file. If the file is missing or contains invalid keys, the system falls back to hardcoded defaults.

Default Shortcuts

Action	Default Key	Config Key
Edit Notes	ctrl+n	editNotes
Queue Step	ctrl+down	queueStep
Toggle Auto-run	ctrl+shift+down	queueToggleAuto

Sources: src/main.ts:139-155, README.md:68-77

Summary

The PlanQueue Extension Architecture provides a bridge between OMP's agent lifecycle and a persistent, user-editable Markdown plan. By treating the note buffer as a stateful FIFO queue, it enables both manual "human-in-the-loop" stepping and automated prompt sequencing, supported by a localized file-based storage system and LLM-accessible tools.