Cross-session Browser Picker
Relevant source files
The following files were used as context for generating this wiki page:
The Cross-session Browser Picker is a core feature of PlanQueue that allows users to access and view notes from different sessions within the same repository and branch. It provides a keyboard-driven interface to list and select historical or parallel notes, facilitating context retrieval without requiring the user to leave their current active session.
This system effectively acts as a bridge between the current session and the persistent storage layer, which organizes Markdown notes by repository and branch under the ~/.planqueue/ directory.
Sources: README.md:58-60, src/main.ts:85-87
Architecture and Data Flow
The browser picker operates by scanning specific directory structures to aggregate session notes. It prioritizes the modern storage path but maintains backward compatibility by merging results from legacy storage locations.
Search Locations and Resolution
The system identifies relevant notes based on the current context (repository and branch). The following paths are scanned:
- Primary Path:
~/.planqueue/{repo}/{branch}/ - Legacy Paths:
~/.free-text/and~/.omp-free-text/
Sources: src/main.ts:89-98, README.md:88-93, tests/core-integration.test.ts:18-24
Logic Flow for Note Retrieval
The logic ensures that if a session ID exists in multiple storage roots, the version from the newest root is preserved while duplicates from older roots are discarded.
The diagram shows the sequence of directory scanning, data merging, and UI presentation.
Sources: src/main.ts:100-130
User Interface and Interaction
The feature is exposed through the /planqueue slash command. When executed, it launches a ctx.ui.select interface (a keyboard picker) that presents available notes with a preview and a timestamp.
Picker Metadata
Each option in the picker includes:
- Label: A formatted string containing a timestamp (
YYYY-MM-DD HH:mm) and a preview of the note content. - Description: The unique
sessionIdassociated with that note.
Sources: src/main.ts:121-127, CHANGELOG.md:23-24
Read-only Viewer
Once a note is selected, the content is displayed using the CustomEditor component. Crucially, when opened via the browser picker, the result of the editor session is ignored, ensuring the browser remains a read-only viewer and does not accidentally overwrite the current session's data.
Sources: src/main.ts:133-140
Key Components and Functions
The implementation relies on several internal functions and SDK methods to manage the lifecycle of the browser picker.
| Component | Type | Description |
|---|---|---|
browseNotes | Function | Orchestrates the listing, filtering, and selection UI for cross-session notes. |
listNotes | Core Function | Reads a directory and returns NoteSummary objects containing paths, previews, and timestamps. |
makeNotesEditor | Function | Constructs the CustomEditor instance used for both editing and viewing notes. |
/planqueue | Command | The user-facing slash command that triggers the browseNotes logic. |
NoteSummary | Data Structure | Contains sessionId, path, preview, and mtimeMs. |
Sources: src/main.ts:54-73, src/main.ts:85-110, src/main.ts:413-424
Security and Persistence
The Browser Picker adheres to the project's security policy regarding file I/O. It only performs read operations on the designated note directories and does not provide an interface for the agent to browse files across sessions; it is strictly a human-initiated UI feature.
- File I/O: Limited to
~/.planqueue/,~/.free-text/, and~/.omp-free-text/. - Context: Notes are isolated by the repository's top-level directory and the current git branch.
Sources: SECURITY.md:23-29, src/main.ts:316-324
Summary
The Cross-session Browser Picker provides an essential context-management tool within PlanQueue. By leveraging the structured storage of Markdown notes and a keyboard-centric selection UI, it allows developers to quickly reference plans and notes from previous or concurrent work sessions without disrupting their current workflow. Its implementation ensures data integrity through read-only viewing and provides a seamless transition for users through comprehensive legacy path support.
Sources: README.md:58-60, src/main.ts:100-105