User guide / Workspaces and persistent sessions

The session manager

Development reference · View source

Space Space or :session-list (:sl) opens a filterable list of running and recently visited sessions, on Unix and Windows.

  No. Name                    Branch            Path                             Last active  Status
  1   main                    main              ~/code/runyte                   3h ago
  2 * runyte-dev              dev               ~/code/runyte-dev               0min ago
  3   Brain                   -                 ~/Brain                         12days ago
  4   runyte.github.io        main              ~/code/runyte.github.io         5days ago     QUIET
  5   runyte-enh-render-space enh/render-space  ~/code/runyte-enh-render-space  1min ago

The title reads Sessions · Enter open · Tab actions · Esc close.

Manager keys

• Space Space is the complete binding, not a prefix. Once the filter has text, Space is filter text and only Escape or Ctrl-c closes.
• Digits are shortcuts only while the filter is empty, because default names such as runyte-2 and many paths contain digits. Clearing the filter (Delete, or Backspace to empty) arms them again. A name or path starting with a digit therefore cannot be filtered by that first character; type a later part.
• Space Space 1 reaches the first session in one gesture.

The key legend is pinned, dimmed, to the bottom. It names only keys that act now: 1-9 attach while the filter is empty in a persistent editor, the Ctrl-o, Ctrl-e, and Ctrl-g chords while they can act, moving and paging, Home/End, Ctrl-t, and Delete while there is a filter. Rows take priority: in a short manager the legend first loses its spacing line, then disappears, before any row is hidden.

The Tab menu lists the selected row’s actions first, then, under a Manager heading, the manager’s own actions with their direct keys:

• Open is the same as Enter.
• Close stops the host and keeps the workspace as a stopped row. Nothing below the session is touched, because a session is the only level that means nothing on its own.
• Forget removes only the history record behind a stopped row. Nothing in the project is touched; naming the directory again starts a host there and lists it again.
• An entry that cannot act here, such as Git worktrees outside a repository, is dimmed with the reason and refuses without closing the manager.

Columns

• Columns are padded to the widest value or heading so they line up. Headings stay above the rows and are not filtered or selectable.
• The branch is read from the directory itself, not from a host, so a stopped session shows its branch too.
• When a row is too wide beside the preview, the middle identity columns are clipped, keeping Last active and Status together.
• The current session is the initially selected row.

Last active uses one unit at a time: 5min ago, 3h ago, 5days ago.

• Partial units round up, even across a boundary: 59 minutes and one second reads 1h ago.
• The current session reads 0min ago. Leaving it records the end of the visit, and ages keep advancing while the manager is open.
• A history entry with no recorded visit reads - until visited again.

Status reports plugin work first, in this order, and otherwise terminal output:

Two conditions are also written on the row:

• missing directory in the status: the project directory is gone while its host still runs.

• health unavailable: a running host did not answer its health request.

• The selected row’s preview names each activity’s owner, title, and state.

• For QUIET, a new terminal starts the two-minute clock without counting its empty first row. Line feeds, index/new-line controls, automatic wraps, and top-anchored primary-screen scrolls complete lines. Partial text, carriage-return rewrites such as spinners, cursor-only movement, application scroll regions, alternate-screen repainting, and resizes do not. Exited terminals do not count. QUIET does not claim a process is idle, blocked, finished, or unhealthy.

• A health unavailable row shows - for terminals, buffers, unsaved buffers, waits, and attached TUI. They are unknown, so a missing count is not evidence that the session is safe to stop. A confirmed zero shows 0, and the unsaved count is the host’s own answer, so a healthy row showing Unsaved 0 is one the host will agree to stop.

• A missing directory row keeps its number and place so it can be found and closed. Its history survives for the same reason. A stopped session with nothing left to open leaves the list without giving its digit away.

• While open, the manager asks each compatible running host for this bounded health at most once every five seconds. It never fetches terminal contents or reads activity from the preview.

Preview

Ctrl-t toggles the preview in the right column. The choice holds while the selection moves and rows refresh; reopening the manager starts fresh.

Active: 0min ago
Status      running
Panes       2
Terminals   2 (1 exited)
Buffers     9
Unsaved     0
Waiting     0
Attached    yes
Branch      enh/render-space
Directory   /home/me/code/runyte-enh-render-space
Worktree    yes
Repo        git@github.com:me/runyte.git

• Every row answers the same questions in the same order, so two sessions are compared by reading one place.
• - means nothing can answer, which is deliberately not 0.
• Terminals 2 (1 exited) counts retained exited screens beside live ones, since they are not live state.
• Panes comes from a bounded, read-only request for the selected row only, which never becomes a second attachment. It reads … while in flight and - for a stopped session or another protocol version.
• Worktree is yes only for a linked Git worktree; no for a main checkout or a non-repository. A .git file alone does not make a worktree: a submodule and a --separate-git-dir repository both have one for their own main checkout.
• Nothing in the preview is saved for later listings.
• Buffer and terminal contents are not shown: at this width a snippet is neither readable nor useful as identity.

Numbers and order

Sessions carry a number from 1 to 9.

• Order. Numbered sessions lead in digit order, so the digit tells both which key reaches a row and where it is, and the top of the list stops rearranging as you visit. The rest follow by Last active, least recently visited first, with never-attached sessions (-) at the very bottom.
• Only running sessions are numbered. A stopped row has no digit, drops below the numbered ones, and gives up all numbering state. A stopped row is drawn in the dimmed text colour, so running hosts stand out without hiding any row.
• Automatic numbers close gaps in their existing order, and a new session takes the lowest free digit: with three running sessions, the next is 4 even if stopped history used to hold it. Sessions with no recorded creation order are numbered most-recently-visited first.
• Only nine are numbered at a time; a tenth is reached by name or path.
• Missing numbers. A numbered shortcut with no session reports an error. Shortcuts never restart a stopped session or take over an occupied TUI.

Renumber (Tab menu, running rows only) opens a prompt for one digit, then returns to the manager.

• A number another session holds is swapped, so both keep a shortcut. The displaced session may be renumbered automatically later.
• An empty answer removes the number and keeps it removed while the session runs: the session stays in the by-visit part of the list until numbered by hand or stopped.
• A number chosen this way is pinned while the session runs and reserved before automatic numbering.