Shelf View

Worktrees as vertical “book spines” stacked on the side — flip through your whole stack from the keyboard, never losing your place.

Keywords:shelfbookspinevertical tabsflipcycle bookscycle tabstriageproximitystack

Related: view-modes · canvas · terminal · active-agents · keyboard-shortcuts

What it is#

Shelf lays your worktrees out as thin vertical spines (“books”) on the sides, with the currently open book’s terminal filling the center. Each spine shows the project icon/name (rotated) and a column of its tabs as small icon slots. When Prowl detects an agent in a tab, that tab slot shows the agent status as a small colored marker. Books near the open one are brighter; distant ones fade — so you always know where you are in the stack.

Toggle Shelf: ⌘⇧↩ (toggle_shelf). Requires at least one open worktree; otherwise it’s a no-op.

Keyboard navigation (the whole point)#

So ⌘⌃←/→ moves between agents, and ⌘⌃↑/↓ moves between that agent’s tabs — triage six in-flight agents one keystroke at a time.

Hold ⌘ and use a two-finger trackpad swipe for directional navigation: horizontal swipes flip between books, and vertical swipes cycle tabs in the open book. Both axes wrap around, matching the ⌘⌃ arrow keys. Plain scrolling inside the terminal keeps working normally because Shelf only consumes the gesture while ⌘ is held.

Interacting with spines#

• Open a book: click anywhere on a closed spine (it activates and shows its terminal).
• Select a tab: click a tab slot on the open book’s spine.
• New tab: the + at the bottom of a spine. On a closed book, + opens the book and creates the tab.
• Jump to an agent: click a tab slot with an agent status marker. It focuses that agent’s worktree, tab, and pane.
• Split: the open book’s spine has split-vertical and split-horizontal buttons (Ghostty new_split:right / new_split:down).
• Close a tab: hover a tab slot → its ×.
• Tab context menu: right-click a tab slot → Rename, Change Icon, Close, Close Others, Close to Right, Close All.
• Spine header context menu: right-click → Repo Settings, Close Worktree/Folder (closes all its tabs, removing the book).

While holding ⌘, the open book overlays its tab slots with 1…9 hints for quick selection.

Visual cues#

• Open book: full-strength color. Neighbors: ~50%. Farther books fade progressively — a proximity ladder that keeps the stack readable.
• Unread notification: a tab slot highlights orange; the spine header shows an orange dot.
• Detected agents: status markers appear on the owning tab slot. Marker color/status follows the Active Agents states (Working, Blocked, Done); idle agents tint the slot but show no corner glyph. Blocked agents are prioritized first when a split tab contains multiple agents. Shelf keeps agent detection active while visible, even if the Active Agents panel is hidden.
• Spine tint follows the repository color when set (toggle shelfSpineTintFollowsRepositoryColor); otherwise a fallback (shelfSpineTintFallback: neutral or system tint) is used.
• In Shelf, the toolbar and leading band are tinted with the open book’s repo color (windowTintMode).

Empty state#

If no book is open, the center shows “No worktree selected” with a books icon; spines stay visible so you can pick one.

Settings that affect Shelf#

• defaultViewMode — launch directly into Shelf.
• showActiveAgentStatusInShelf — overlay detected agent status on Shelf tab icons.
• shelfSpineTintFollowsRepositoryColor — color spines by repo color.
• shelfSpineTintFallback — neutral or systemTint when a repo has no color.
• windowTintMode / repository colors — chrome tinting.

When to recommend Shelf vs Canvas#

• Shelf = linear, keyboard-driven, see-one-at-a-time triage of many worktrees. Fastest way to cycle through agents and check each.
• Canvas = spatial, all-at-once supervision and broadcast.

See view-modes.

Gotchas for agents#

• A “book” is a worktree; a tab slot is a tab within it.
• Agent status markers belong to the terminal surface’s owning tab/worktree. If an agent is running from a different working directory, the full Active Agents panel still shows the resolved repository/branch context.
• Closing the last tab of a book removes the book from the shelf.
• The book-cycling keys (⌘⌃←/→) and tab-cycling keys (⌘⌃↑/↓) differ only by arrow direction — be precise when describing them.