Notes Panel & Editor
Relevant source files
The following files were used as context for generating this wiki page:
The Notes Panel & Editor is the central user interface component of the PlanQueue extension for OMP (Oh My Pi). It provides a persistent, editable workspace where users can write plans as plain text or Markdown-style tasks. This system serves a dual purpose: it acts as a session-specific scratchpad and functions as a FIFO (First-In-First-Out) prompt queue that can be dispatched to an AI agent line-by-line.
The panel is rendered below the OMP status line, showing real-time status glyphs for queued tasks. The system ensures data persistence across sessions, repos, and branches, while providing sophisticated features like auto-normalization of tasks, history tracking, and cross-session note browsing.
Sources: README.md:9-12, src/main.ts:8-14
Architecture and UI Components
The system is built using the OMP Extension SDK and consists of three primary UI layers: the HUD Widget, the Custom Editor, and the Cross-Session Browser.
HUD Widget
The widget is the primary visualization tool, placed via ctx.ui.setWidget with the belowEditor placement. It renders the content of the current note, using specific glyphs to represent the state of each line in the queue.
- Placement:
belowEditor - Visual Glyphs:
☐: Pending task (- [ ])▸: In-flight task (- [>])✓: Completed task (- [x])
Sources: src/main.ts:187-199, README.md:65-70, CHANGELOG.md:16-18
The Notes Editor
The editor is a multi-line overlay triggered by Ctrl+N or the /note command. It leverages the sdk.CustomEditor to provide a native-feeling input experience within the OMP environment.
The diagram shows the lifecycle of an editing session from user initiation to persistent storage.
Sources: src/main.ts:60-75, src/main.ts:318-333
Data Persistence and Storage
PlanQueue uses a structured file system hierarchy to ensure that notes are contextualized to the specific development environment.
Storage Hierarchy
Notes are stored as plain Markdown files in the user's home directory.
| Component | Path Template |
|---|---|
| Active Note | ~/.planqueue/{repo}/{branch}/{session-id}.md |
| History File | ~/.planqueue/{repo}/{branch}/{session-id}.history.md |
| Global Config | ~/.planqueue/config.json |
| Legacy Paths | ~/.free-text/ or ~/.omp-free-text/ (Read-only) |
Sources: README.md:104-108, src/main.ts:219-224, SECURITY.md:21-25
Persistence Logic
The system implements a debounced saving mechanism (createDebouncedSaver) to prevent excessive disk I/O during rapid editing. Every successful save also triggers an append-only update to a sibling .history.md file, providing a recovery path for discarded drafts.
Sources: src/main.ts:241-250, src/main.ts:143-163
The Prompt Queue System
The notes editor content is parsed as a FIFO queue. Lines are categorized based on their prefix and indentation.
Line Parsing and Dispatch
- Tasks: Lines starting with
- [ ](or auto-normalized plain lines) are treatable as prompts. - Continuation Lines: Indented lines following a task are treated as part of the same prompt block and sent as a single multi-line message.
- Barriers: A line consisting of
---acts as a human-in-the-loop barrier, pausing auto-run. - Prose: Lines starting with
#(headings) or>(quotes) are ignored by the queue controller.
Sources: README.md:73-82, src/queue-controller.ts:110-120
Queue Controller Flow
The queue-controller.ts manages the state transitions of tasks within the note.
This flowchart illustrates how a task moves from pending to completed, including the interaction with the OMP agent.
Sources: src/queue-controller.ts:133-157, src/queue-controller.ts:186-192
Extension Commands and Tools
The system provides several interactive commands and agent-accessible tools to manipulate the note buffer.
Slash Commands
| Command | Description |
|---|---|
/note | Opens the editor. If text is provided (/note <text>), it appends it as a task. |
/planqueue | Opens the cross-session browser to view notes from other sessions in the same repo/branch. |
/make-note | Accepts a <goal> and asks the agent to decompose it into a full queue using the make_note tool. |
Sources: src/main.ts:420-445, README.md:88-102
Agent Tools
note_add: Allows the agent to append a single- [ ]task to the note.make_note: Allows the agent to overwrite or bootstrap a note with a structured plan, including headings, prompts, and barriers.
Sources: src/main.ts:355-364, src/main.ts:391-410
Configuration and Shortcuts
Shortcut keys are configurable via ~/.planqueue/config.json. The system defaults to specific keys if the config is missing or malformed.
| Action | Default Shortcut | Config Key |
|---|---|---|
| Edit Notes | ctrl+n | editNotes |
| Queue Step | ctrl+down | queueStep |
| Toggle Auto-Run | ctrl+shift+down | queueToggleAuto |
Sources: README.md:118-124, src/main.ts:166-180
Summary
The Notes Panel & Editor transforms static session notes into an active control surface for AI-driven development. By combining a persistent Markdown-based storage system with a stateful queue controller and agent-integrated tools, it allows for seamless "write once, run many" workflows. The inclusion of history tracking and cross-session browsing ensures that context is never lost, while the HUD widget provides immediate feedback on the progress of the automated plan.