User guide / Workspaces and persistent sessions

Session and destination navigation

Development reference · View source

The Navigator

Space n (or Ctrl-w n) opens the Navigator: a fuzzy picker of open buffers and running terminal sessions.

• Ctrl-w n works in editor modes and Terminal Insert and follows keys.window. Space n is child input in Terminal Insert.
• No filesystem scan or content search runs here; Space f is the Finder.
• With editor.auto_close_terminal: false, exited terminals stay in Space t t, whose Tab menu offers Close all exited terminals without touching live children.

The Navigator, the buffer list (Space b b), and the terminal list (Space t t) are one list over three scopes — every open destination, the buffers, or the terminals including retained exited ones — with the same columns:

    TYPE        NAME                           STATE
  * [scratch]   scratch                        [+]
  * [file]      README.md                      [+]
    [about]     about                          [RO]
    [file]      /tmp/prompt-8e155cfe…90d4.md   [STALE]
    [explorer]  .
  * [terminal]  ✳ Article usage in mode descriptions
    [terminal]  user@host:~/code/runyte-dev    exited

• Scratch and retained special buffers appear once per identity.
• Lists open in recent activation order, and keep that order while filtering. The terminal list puts running terminals first and dims exited ones.
• Names, paths, terminal titles, launch commands, and running terminals' numbers (3 or #3) match fuzzily, with matched characters emphasized.
• A terminal’s preview shows its live screen, updating as output arrives and as the selection moves, even for hidden or reviewed terminals. Previewing does not focus or resize it. A running terminal’s number is in its pane title ([terminal #3] …).

• Printable j, k, and q filter.
• Cancelling from Terminal Insert resumes child input. Visiting a document enters Normal; visiting a live terminal resumes Insert unless it holds a review.
• Visiting a destination already visible focuses its pane. Bring into active pane places it here instead. A PTY always has one live view.

Previous destination. Ctrl-w p (previous-destination) returns to the previous open destination in this pane, skipping closed resources and exited terminals.

Switching sessions

• Shift-Left / Shift-Right visit the previous/next running session in manager order, including unnumbered ones, wrapping at the ends. They work in Insert and Terminal Insert as remappable exceptions to child input, subject to open overlays and confirmations. They never start a stopped session or force an occupied attachment. If an outer tmux takes Shift-Left/Right, release or change those tmux bindings.
• Ctrl-w a (previous-session) alternates between the last two successful attachments. Failed switches leave that history alone.
• Every attachment refreshes the session list in the background, including when returning to a host whose cached list predates a newly started session.

The session strip

The session strip sits above the editor area.

• Zen hides it.

• Left-click an entry to switch to that running session, numbered or not. Clicking the current entry, empty space, or the overflow count does nothing. Prompts and overlays keep input ownership.

• Entries keep manager numbers and names. Overflow keeps the current entry visible and shows how many were left out as a trailing …N.

• Every entry has exactly one state marker, so a name sits in the same cells whatever its session is doing. In order of precedence:

  Marker	Meaning
  ?	Unknown health (distinct from stopped)
  !	A terminal bell
  +	Unread terminal output
  ·	Quiet

• Unread output and bells follow the terminals’ viewing rules: entering a session does not acknowledge its hidden terminals. QUIET in the manager still describes completed-line output, not job completion.

Opening another directory

• The directory chooser (Ctrl-o in the manager) offers recent roots, sibling worktrees, typed paths, and directory browsing. Open this directory selects the shown root; descending into a child is a separate action. On Windows it accepts drive paths and backslashes; recent-root and worktree shortcuts are Unix-only for now. Worktree creation is explicit.
• Tab s in an explorer offers Open persistent session here for the directory it shows, even when empty.
• A terminal’s action menu can open its last validated OSC 7 directory, and explains when there is none.
• Open destinations (Ctrl-e) inspects the selected running session’s open destinations; Escape returns. Choosing one attaches and revalidates it; a resource closed meanwhile leaves the restored layout intact and reports the loss.

These routes initialize or reuse the exact directory’s persistent session and keep the source host and its terminal processes.

From inside an integrated terminal, cd ../worktree then runyte -a switches the outer TUI to that directory’s workspace, a Git worktree here. Outside any workspace it refuses; runyte -a DIRECTORY names a directory to make one.

• Relative arguments resolve from the shell’s directory.
• The command returns to the shell without starting a nested TUI; switching back returns to that shell.
• The route checks the owning host, terminal, and caller, and reports the attachment or its error. Stale, detached, or ide-mode parent contexts get an actionable error.
• Outside integrated terminals, launching works as usual.