Agent Queue Appending (note_add)

Relevant source files

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

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

The note_add feature is a core component of the PlanQueue extension that allows an LLM agent to programmatically interact with the user's prompt queue. Within the PlanQueue system, the session note functions as a First-In-First-Out (FIFO) queue where each line represents a task or prompt. The note_add tool specifically empowers the agent to append new tasks to the bottom of this active note, enabling a dynamic planning process where the agent can "remember" or schedule future work items based on the current conversation.

Sources: README.md:9-14, src/main.ts:251-255

Architecture and Tool Registration

The note_add functionality is implemented as a registered tool within the OMP (Oh My Pi) extension framework. It is automatically available in every session once the PlanQueue extension is installed. The tool is defined in the extension's entry point and utilizes the @oh-my-pi/pi-coding-agent SDK for tool registration and lifecycle management.

Tool Definition

The tool is registered with specific metadata that guides the LLM on when and how to use it:

• Name: note_add
• Label: "Add to note"
• Approval Level: write (requires permission to mutate the note file)

Sources: src/main.ts:251-267, CHANGELOG.md:27-30

Execution Flow

When the agent invokes note_add, the system validates the existence of an active note for the current session. If a note exists, the tool appends the provided text as a new task line. The PlanQueue core logic ensures that these appended items are automatically formatted as - [ ] checkboxes, marking them as "pending" in the FIFO queue.

The diagram shows the interaction between the LLM agent and the PlanQueue plugin to persist a new task.
Sources: src/main.ts:271-294, README.md:52-54

Data Models and Parameters

The note_add tool uses a strict schema for its input parameters, validated via the zod library. This ensures that the agent provides the necessary information in the correct format.

Input Parameters

Parameter	Type	Description
text	string	The task text to append (rendered as a single line).

Sources: src/main.ts:262-265

Output Format

The tool returns an AgentToolResult containing a confirmation message that is displayed in the agent's transcript. If no note is active, it returns an error message indicating that the session note could not be found.

Sources: src/main.ts:276-291

Integration with Persistence and History

Appended notes are not merely held in memory; they are integrated into the project's robust persistence layer.

• Debounced Saving: When note_add triggers a persist call, the content is handled by a DebouncedSaver. This prevents excessive disk I/O while ensuring the note is eventually written to ~/.planqueue/{repo}/{branch}/{session-id}.md.
• History Tracking: Every successful append via the agent is also recorded in a sibling .history.md file. This provides an append-only audit trail of how the queue has evolved through both human and agent edits.
• Widget Synchronization: Immediately after the agent appends a task, the refreshWidget function is called to update the UI panel below the status line, showing the new task with its pending glyph (☐).

Sources: src/main.ts:397-414, src/main.ts:333-338, SECURITY.md:23-28

Security and Permissions

Because the note_add tool performs local file I/O, it operates under specific security constraints defined in the project's security policy:

• Scope Limitation: The tool can only mutate the note buffer of the current session. It cannot read or write arbitrary file paths outside the ~/.planqueue/ directory tree.
• Approval: It is categorized as a "write" tool, meaning the OMP environment handles the necessary permissions for the extension to modify local Markdown files.

Sources: SECURITY.md:23-28, src/main.ts:267

Usage Comparison

note_add is one of several ways the agent can interact with the queue.

Feature	Primary Actor	Use Case	Resulting Format
note_add	Agent	Appending a single task mid-conversation.	- [ ] Task text
make_note	Agent	Decomposing a large goal into a full plan.	Multiple - [ ] and ---
/note <text>	User	Manually adding a single task via command.	- [ ] Task text

Sources: README.md:52-60, src/main.ts:317-322

Conclusion

The note_add tool is a critical bridge between agent reasoning and the PlanQueue execution engine. By allowing the agent to programmatically manage the prompt queue, it enables "Plan-then-Execute" workflows where the agent can self-organize tasks into a structured, human-auditable Markdown format that the user can later drive via auto-run or manual stepping.