Installation & Setup

Relevant source files

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

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

PlanQueue is an extension for the Oh My Pi (OMP) coding agent harness. It provides a session-notes panel that functions as a FIFO (First-In-First-Out) prompt queue, allowing users to plan multi-step work and dispatch prompts sequentially. Installation and setup involve integrating the extension into the OMP environment, either via OMP's built-in plugin manager or through manual development linking.

Sources: README.md:10-14, package.json:3-5

General Installation

PlanQueue can be installed directly from GitHub or from the npm registry using the OMP CLI. As the repository is public, no GitHub authentication is required for installation.

Installation Commands

Method	Command	Description
GitHub	omp plugin install github:aryrabelo/planqueue	Installs the latest version from GitHub.
npm	omp plugin install @aryrabelo/planqueue	Installs the package via npm.
Specific Version	omp plugin install github:aryrabelo/planqueue#main	Installs from a specific branch, tag, or commit.

Sources: README.md:46-56

Verification and Management

After installation, users can manage the extension status using the following OMP commands:

• omp plugin list: Confirms if the extension is loaded and enabled.
• omp plugin install ...: Re-run the installation command to update to the latest version.
• omp plugin uninstall @aryrabelo/planqueue: Removes the extension from the environment.

Sources: README.md:58-62

Development Setup

For contributors or developers looking to modify the extension, the project requires the Bun runtime (version 1.0.0 or higher).

Initial Environment Setup

1. Clone and Install: Clone the repository and install dependencies using Bun.

   bun install
   

2. Link to OMP: To test the local version within an OMP harness, use the link command:

   omp plugin link
   

Sources: CONTRIBUTING.md:5-9, 29-33, package.json:37-39

Development Workflow

The project uses Biome for linting and formatting, and TypeScript in strict mode for type safety.

This diagram illustrates the required verification steps before opening a pull request.
Sources: CONTRIBUTING.md:13-25, biome.json:1-30

Configuration

PlanQueue uses a global configuration file located at ~/.planqueue/config.json. This file is used to override default keyboard shortcuts.

Shortcut Configuration

The following shortcuts are defined by default but can be customized:

Action	Default Key	Config Key
Open/Edit Notes	Ctrl+N	editNotes
Dispatch Next Prompt	Ctrl+Down	queueStep
Toggle Auto-Run	Ctrl+Shift+Down	queueToggleAuto

Sources: README.md:126-146, src/main.ts:168-181

JSON Configuration Example

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

If the configuration file is missing or malformed, the system falls back to these defaults and logs a warning.
Sources: README.md:131-139, src/main.ts:173-181

Persistence and Storage

PlanQueue automatically manages the storage of notes based on the current Git context.

The storage architecture ensures notes are isolated per project and branch while maintaining an append-only history of all changes.
Sources: README.md:148-154, src/main.ts:333-356

Storage Locations

• Active Notes: ~/.planqueue/{repo}/{branch}/{session-id}.md
• Change History: ~/.planqueue/{repo}/{branch}/{session-id.history.md}
• Global Config: ~/.planqueue/config.json
• Legacy Fallback: The extension reads from ~/.free-text/ and ~/.omp-free-text/ for backward compatibility but only writes to the new paths.

Sources: README.md:148-158, src/main.ts:350-362

Summary

Installation of PlanQueue is handled via the OMP plugin system, supporting both GitHub and npm sources. Once installed, the extension requires zero manual configuration to function, as it automatically resolves storage paths based on the user's working directory and Git status. Advanced users can customize interaction through a central JSON configuration file, while developers can utilize the provided Bun-based toolchain for verification and testing.

Sources: README.md:46-62, 126-146, CONTRIBUTING.md:5-25