Pickle HUD and dock

Pickles are independent Pi sessions shown in the Picky HUD dock. They are useful for long-running work that should continue in the background.

The dock can be vertical or horizontal and can attach to the screen edge. When pinned, its visible edge sits 4pt inside the screen’s usable area (excluding the menu bar and macOS Dock); transparent shadow padding does not add to that gap. The vertical dock rests as a narrow icon column and widens to show names and controls when you hover. The horizontal dock keeps square icon cells and reveals one shared title-and-actions row on hover instead of widening every cell. Its handle sits at the top in vertical mode (left in horizontal mode); the compact action controls and collapse notch sit at the opposite end. When no conversation card is open, the transparent space reserved beside the dock passes clicks to the app underneath.

Dock states

Pickle status can be:

Status	Meaning
queued	Waiting to run.
running	Actively working.
waiting_for_input	Needs user input.
blocked	Blocked or paused.
completed	Finished successfully.
failed	Failed.
cancelled	Stopped/cancelled.

The dock row’s glyph color, trailing dot, and completion flash reflect these states. A running Pickle shows a ring around its glyph; Pickles that need you (waiting for input, blocked, failed) show a colored dot at the end of the row, and an unread Pickle shows a blue dot instead. A blocked Pickle uses a diamond dot and a pause-eyed glyph, so it stays distinct from a failed one without relying on color.

Dock interactions

Interaction	Result
Hover a Pickle	Reveals its name and archive button. In horizontal mode, the shared preview row shows its title, status, and archive button.
Click a Pickle	Opens or closes its conversation card.
Press and hold a Pickle	Archives it after a ~1.2s hold timer; the row fills from the left while you hold, and moving the cursor more than ~10pt away cancels the archive before it fires. Archives are recoverable from the undo toast or Hub → Settings → Pickles and workspace → Archived sessions.
Drag a Pickle	Reorders dock Pickles, or drags one into / out of a group. The move is committed when you release. Hold it clearly outside the dock for a moment and an Archive label appears; release there to archive it (macOS Dock style).
Right-click / Control-click	Opens the dock context menu. Use Pin Picky Input to This Pickle to keep routing voice and Quick Input here, or Send Next Picky Input to This Pickle for one message only. The menu also provides Compact, Move to Group, Remove from Group (for grouped Pickles), Archive, and Stop; Stop is disabled when the Pickle can no longer be stopped.
Drag the tab on the dock’s inner edge	Resizes the dock between S, M, and L on this display only. The tab appears while the pointer is over the dock. Each display remembers its own size, just like its dock position and orientation; there is no size selector in Settings.
Click the ribbon at the top corner of the expanded vertical dock	Pins the dock open on this display: the ribbon turns blue and hangs lower, and the dock no longer collapses when the pointer leaves. Click it again to unpin. Each display remembers its own pin across restarts. The ribbon sits on the name side, opposite the handle, and hides while the dock is collapsed.
Click the + slot	Opens a popover with pinned/recent folders, Choose Folder…, and New Group….
Drag the dock handle	Move the dock along or across screen edges. The dock may tuck partly off-screen, but its handle slot stays visible so it remains grabbable.
Double-click the dock handle	Toggle the dock between vertical and horizontal layouts.
Click the notch at the bottom (right in horizontal mode)	Minimize the dock to a Picky logo button at the handle end. Click that button to expand the dock, or drag it to move the minimized dock without expanding it. While minimized, a badge on the button counts unread Pickles (the same Pickles that show an unread dot in the expanded dock).

Number shortcuts (Cmd + 1…9) apply to the first 9 visible Pickle rows, top to bottom (left to right in horizontal mode), including rows inside expanded groups. Group headers and the members of a collapsed group take no number. While Cmd is held, every numbered row shows its badge.

Dock sizes:

Size	Vertical dock	Horizontal dock
S	Expands to 112pt wide, one-line rows	36pt square cells
M (default)	Expands to 168pt wide, one-line rows	36pt square cells
L	Expands to 200pt wide, two-line rows with status and time	47pt square cells

At the default font scale, the vertical dock rests at 36pt wide and the horizontal title preview adds 30pt when revealed. S uses slightly smaller title text; larger sizes leave more room for names.

When the rows do not fit, only the list scrolls; the handle and bottom buttons stay put, and the edge that hides rows fades out. A horizontal dock stops growing at 720pt (or the screen width, whichever is smaller) and scrolls sideways beyond that.

Creating an empty Pickle

Click the + slot in the dock to open the Recent folders popover:

• Pick a pinned or recent working folder to start an empty Pickle there immediately.
• Use the pin button on a recent folder to keep it at the top of the list. Pinned folders stay visible ahead of recents and are not removed by the recent-folder cap. Drag a pinned folder by its grip to change the pinned order.
• Use the unpin button to move a pinned folder back into the regular recent list, or the remove button to hide an unpinned recent folder.
• Choose Folder… opens the macOS folder picker for any other folder.
• New Group… creates a dock group instead of a Pickle (see §7.4).

When you start a Pickle this way, Picky creates an empty Pickle for that folder and, if it is visible, opens it automatically.

Pickle groups

Group related Pickles under a header in the dock. A group uses a colored folder icon (filled when collapsed, outlined when expanded). Its name, active Pickle count, and rounded-square color control appear in the expanded vertical dock or the horizontal preview. Click the header to collapse or expand the group; its members appear right below it (to its right in horizontal mode). An expanded group’s header and members share one card tinted with the group color, so grouped Pickles stand apart from ungrouped ones even when the dock shows only icons. Each display remembers its own expanded or collapsed state. Group names, colors, membership, and ordering remain shared across displays. A collapsed header shows a single blue dot when any member is unread or still needs you (waiting for input, blocked, or failed), even after you read it. A collapsed folder also shows a running badge on the opposite corner while members are working: a ringed Pickle for one running member, or the number running for two or more (9+ beyond nine). The badge hides when you expand the group, because each member row shows its own running ring.

Create a group:

• Click the + slot → New Group…, give it a name, and optionally pick initial Pickles and an accent color.
• A new group opens expanded. An expanded group with no Pickles shows a Drop a Pickle placeholder; drag Pickles onto it, or click it to start a Pickle in that group. In the vertical dock, the placeholder has the same size as a Pickle row, shows Start Pickle on hover, and shows Drop here while a dragged Pickle is over it.
• In the horizontal dock, an expanded group with Pickles ends in a narrow + slot inside its card. Click it to start a Pickle in that group from a recent folder.

Manage membership:

• Ask the Picky main agent to organize existing Pickles. It uses the local picky CLI to list groups, create a named group, add/remove exact Pickle session IDs, or ungroup while keeping members. These operations update the same persisted dock layout used by the UI.
• Drag a Pickle onto a group to move it in; drag it above the first slot or below the last slot to pull it back out to the top level. The dock previews where it will land and commits the move only when you release.
• Drag a group header to reorder the whole group within the dock. Hold it clearly outside the dock and a Remove label appears; release there to remove the group (macOS Dock style). A group with active Pickles asks for confirmation before archiving them; an empty group or one whose members are already archived is removed immediately.
• Drag a Pickle onto a collapsed header to add it to that group, or between the rows of an expanded group to place it at that position. Members keep the order you arrange; a new reply does not move a Pickle.

Hover a group header to reveal:

Control	Behavior
+	Opens the recent-folder picker; the new Pickle joins this group.
Color dot	Opens the color menu.

Right-click a group header for more actions:

Action	Behavior
Rename	Rename the group via a dialog.
Color	Pick the group’s accent color.
Ungroup (keep pickles)	Remove the group but keep its Pickles in the dock.
Delete group + archive pickles	Remove the group and archive its active Pickles (with confirmation when any are active; no prompt when the group is empty or only has archived members).

Archiving and undo

Archive methods:

• Press and hold a Pickle row in the dock until the hold timer completes.
• Use the dock right-click menu → Archive.
• Use the conversation card menu → Archive.

If a Pickle has unfinished background work or its status cannot be verified, archiving asks whether to Archive without stopping, Stop and archive, or Cancel. Archiving without stopping hides the Pickle but retains its pending work and any unresolved results; it does not guarantee that work is still running or make the Pickle ready for new input. If stopping or cleanup cannot be confirmed, Picky leaves the Pickle in the dock and shows an error.

After archiving:

• The Pickle leaves the active dock.
• A screen-level Pickle archived toast appears.
• Click Undo within the toast window to restore it.

Restore paths after archiving:

• The screen-level Undo toast (immediate, time-limited).
• Hub → Settings → Pickles and workspace → Archived sessions (footer disclosure, hidden when empty). Each row has a Restore button.
• Asking the Picky main agent to bring it back (e.g. “되살려”, “restore that pickle”), which routes through the same picky_unarchive_pickle path.

Permanently deleting archives:

• Each row in the archived list has its own Delete button with a 4-second confirm.
• The list header also has a Delete all button (visible only when the archive is non-empty) that opens a confirmation alert and purges every archived Pickle from both Picky and the local agent’s session store in one shot. The action cannot be undone.
• Delete archived Pickles after 30 days (Hub → Settings → Pickles and workspace, on by default): each time Picky starts, every Pickle archived more than 30 days ago is permanently deleted, whatever its status. The same setting deletes the records of the main agent Tasks that finished more than 30 days ago and whose result Picky already received; files a Task changed in your folders are not touched. Turn it off to keep archives and Task records until you delete them yourself. The change applies the next time Picky starts.