Overview mode#

A zoomed-out view of every session in the window, modelled on the GNOME Activities overview: sessions are live cards in a grid, workspaces sit in a strip at the top, and a search box filters the cards. It turns mpmux from "one window, one place" into a place to switch between and later connect sessions on several hosts.

Tracking: TODO-3f6a8c21 and its children.

Using the overview#

The overview shows every session in the window as a card. Each card is one pane. The controls below match the code in apps/terminal/src/mpmux/overview.rs.

Open and close#

• Press Ctrl+Alt+O. On macOS press Cmd+Alt+O. Change the key in [keybindings].toggle-overview.
• On a touch screen, swipe up with three fingers.
• Open the command palette and choose Overview. Scripts reach the overview the same way (open-command-palette, set-command-palette-query overview, confirm-command-palette-selection).
• Press Escape, press the same shortcut, or swipe down with three fingers.
• Opening a card also leaves the overview. A 160 ms visual transition follows, without delaying terminal keyboard focus.

Select and open a card#

• Click or tap a card to select it. The card gets a highlight.
• Click or tap the same card twice within 0.4 seconds to open it.
• Press Enter to open the selected card.
• If the card's tab is split, the whole split shows first. Then the chosen pane grows to fill the tab (pane maximize). This shows where the pane lives. The split shows first even when the tab was maximized on another pane.
• Use the arrow keys to move the selection. Up and Down move by one row.
• When the search box does not have keyboard focus, press 1–9 to open the corresponding visible card.
• When the search box has keyboard focus, number keys enter search text.

Search the cards#

Type in the search box. The filter matches the session name, the terminal title, the host, and visible terminal text. A matching terminal line appears below the card name. A local shell matches the word local. The search box has the keys when you open the overview on the desktop. On a touch screen it stays unfocused so the keyboard does not cover the cards; tap it to type.

The overview shows the first 12 matching cards. A header notice reports additional matches. A narrower search can reveal those sessions.

Small cards show a readable text excerpt that ends at the cursor. Large cards show the full terminal grid. Text excerpts omit terminal images. Thumbnails smaller than 120 × 80 pixels freeze until their size changes. Off-screen cards do not update their thumbnails.

A card shows New output when its visible text changes while it is not viewed. A Bell marker takes precedence. Opening the session clears these markers. Command exit status needs shell integration and is not shown yet.

Zoom, pan, and layout#

• Zoom with Ctrl+scroll, Ctrl+Plus, or Ctrl+Minus. A wheel notch is one step; a touchpad scales with the distance you scroll.
• Pan by dragging the canvas, by scrolling, or by Shift+scroll for sideways scrolling on a wheel.
• Ctrl+drag always pans, even when the press starts on a card.
• Zoom stops at [overview].max-zoom. The default is 12.0.

The header carries the layout control and the reset control. Click the layout control to switch modes. It fills green while manual layout is live.

The switch keeps your work:

• Turning auto layout off starts from the positions on screen, so nothing jumps, and cards become draggable.
• Turning auto layout on snaps the cards into the grid.
• Turning auto layout off again restores the positions you dragged them into. The arrangement is kept across the switch.
• In manual layout every card stays inside the visible area, the frame on the minimap. A saved position from another window size or zoom, a reset view, or a card dropped past the edge moves the card back on screen.

In manual layout, drag a card to move it. In auto layout, drag a card left or right to change its place in the order. A blue line marks where the card will go. The order is saved with the config file. On a touch screen the same gestures work with one finger: drag a card, drag the minimap, and tap the layout and reset controls. In both modes, Ctrl+drag pans the canvas, and a drag on the empty canvas pans it. A zoom keeps the point at the centre of the view in place. The positions are saved with the config file, so the arrangement survives a restart.

Panning is free. The canvas always follows the pointer, so a small arrangement can move even when it fits the screen, and the cards can drift past the edge. Click Reset view in the header to bring them back: the pan returns to the origin and the zoom returns to 1.0.

The minimap in the bottom-right corner of the canvas shows the full arrangement:

The minimap always holds all the cards and the frame, so a card that is out of sight still shows on it. Click a point on the minimap to centre the view on that point. Hold the press and drag to move the view continuously.

Open the card menu#

Right-click a card, long-press it for 0.5 seconds on a touch screen, or press Shift+F10 while it is selected. The menu has eight entries:

Tell hosted and local cards apart#

A hosted card shows its host in a blue pill. A local shell shows local in an amber pill.

A hosted card that needs reconnection has an orange outline. The selected card has a thicker outline. The outline remains when you switch tabs and disappears when the session stream recovers.

Reconnect starts a missing stream or cancels the current recovery attempt. The replacement starts after the old attempt ends. This prevents duplicate workers. Cancellation closes the socket for blocked replies and initial snapshots. Iroh cancellation interrupts control and stream-open futures without closing the shared endpoint.

Native connection establishment before socket registration still uses its existing timeout. Initial Iroh endpoint creation also uses its existing timeout. Reconnect does not bypass these setup operations.

Local sessions and connected sessions do not start another connection. Sessions owned by another device require Take Over, not Reconnect.

Decisions (2026-10-03)#

• A card is one session (one pane's terminal), not a whole tab.
• Cards show live thumbnails, refreshed at a reduced rate.
• Desktop and tablet are built together.
• Local shells (desktop) appear as cards too, styled so a local card is told apart from a hosted one at a glance.
• Hosts are scoped per workspace (option A): each workspace (tab) has its own session host connection and its own hosted-workspace sync. A split tab stays on one host; another host means another workspace. Today the host connection is per window (session_client_options, hosted_workspace_id), so moving it to the workspace is a step of its own (TODO-b8e2f4a6).

Direction: a canvas of views#

The overview is the first view of a larger idea: a canvas that organizes different kinds of views, with links between them like nodes in a compositing or node editor (Blender's node editor is the reference; the pie menu already follows Blender). Sessions are the first item kind. Later items could be other views (logs, file browsers, agent panels, the custom sidebars), and links between items carry data: files, text, pipes.

Long term (user, 2026-10-03): an infinite canvas you pan and zoom, with nodes you operate on (select, group, link), and a continuous zoom from the canvas into a session's terminal view.

For phase 1 this means: build the overview as a canvas of positioned items with an item kind, laid out in a grid by default, rather than a fixed grid widget. Item positions are canvas coordinates; a later camera (pan offset and zoom factor) maps them to the screen, and zooming into a card becomes the transition into the terminal. Links (phase 4) are edges between items on the same canvas.

Model#

The model already exists: a tab holds panes, each pane has its own attached_host_session (any host) or a local terminal_session. Overview mode is a new way to look at and arrange that state, not a new store.

A card shows: - the live thumbnail of the terminal grid; - the session label, host (or "local"), and connection state (direct/relay, reconnecting, view-only); - for local shells a distinct treatment, for example a different frame colour and a "local" badge in place of the host.

Interaction#

• Enter: a three-finger swipe up (tablet), a shortcut (desktop), or the pie menu. From a session the current pane shrinks into its card. Three fingers are free: mpmux uses one finger for selection and taps, two for scrolling, so the gesture does not collide with terminal input. Swiping down with three fingers leaves the overview.
• Empty start: with no session the app opens in the overview with a single "+" card; tapping it runs the existing connect pie (host, then session).
• In the overview: tap or Enter opens a card (zooming back in); "+" adds a session on any host; close and rename from a card menu or long press; arrow keys move between cards; typing goes to the search box.
• Workspaces (phase 2): the strip shows each tab as a miniature; drag a card onto another workspace to move it; "+" in the strip adds one.
• Leave: Escape, a three-finger swipe down, or opening a card.

Rendering#

Cards draw the pane's terminal grid at a small scale with the same renderer, not a screenshot, so they stay live. To keep the overview cheap: - only cards on screen are drawn; - a card redraws when its terminal changes, at most a few times a second; - the grid layout is computed from the card count and the window aspect, keeping each card at its terminal's aspect ratio.

The keyboard (in-app or native IME) is hidden in the overview except for the search box.

Phases#

0. Host per workspace (TODO-b8e2f4a6): move the session host connection and hosted-workspace sync from the window to the workspace (tab), so workspaces on different hosts coexist and recover independently.
1. Overview for navigation (TODO-9a4d2b67): card grid for the current workspace, live thumbnails, local/hosted styling, "+" card with the connect pie, open/close/rename, keyboard navigation, search, the three-finger swipe on the tablet. Cross-fade in and out. Delivers quick host switching.
2. Workspaces (TODO-5c8e1f39): workspace strip, create workspaces, drag cards between workspaces on the same host. Multi-select cards and run "group" to get one workspace with a split layout of those sessions (the inverse of zooming out). With hosts per workspace this groups sessions of one host; grouping across hosts would need per-session hosts for that view and stays an open question. Opening a card shows that session maximized (existing pane maximize). Cards from all workspaces, grouped by workspace; "+" adds a session to a workspace or a new workspace on another host (needs phase 0).
3. Zoom animation (TODO-e7b3a5d0): the pane animates into its card and back, following the three-finger swipe on the tablet.
4. Bridges (TODO-4d9f6c12): drag from card to card to link two sessions, then transfer files (reusing the upload and short-code transfer), send text, or pipe data. The same links through mpmux-cli so agents can set them up. Needs its own transport design first.

Open questions#

• Should the overview also list sessions on known hosts that are not open in this window yet (as dimmed cards), or only open ones? Phase 1 shows open sessions only; the "+" card covers the rest.
• How a split tab appears: each pane is its own card; the workspace strip miniature shows the split.