Managing terminal sessions

Development reference · View source

A session outlives the pane showing it.

Space t q shows the pane’s buffer again and leaves the program running. Opening a file in the pane, or closing the split, does the same.
When the program exits, a pane showing it returns to its most recently used buffer (or a scratch buffer) without closing. By default, the terminal session and its output are forgotten and disappear from the Finder and Space t t. Set editor.auto_close_terminal to false in Space o o to retain future exited sessions for review, search, or Close. Changing this setting does not discard sessions already retained.

The terminal list

Space t t (:terminals) lists sessions in the Navigator’s columns (see Session and destination navigation ):

running sessions first, then retained exited ones, dimmed; each group most recently activated first;
exited, unread, and bell in the STATE column;
the program, number, and directory in the preview.

The preview shows the live screen with its colours, updating while you move through the list; an exited terminal shows its final screen. It is read-only and never resizes the terminal. A wider screen is clipped, and a shorter preview keeps the child’s cursor row visible. Ctrl-t toggles it.

Action	Effect
Enter	Visit: focus a pane already showing it, or show it here. An exited session opens in review.
Show (Tab)	Show the session in the active pane. The only action that attaches one.
Bring into active pane (Tab)	Move a session shown elsewhere to this pane; the old pane shows its buffer again. One PTY is never resized by two visible panes.
Rename (Tab)	Ask for a name and return to the list, leaving panes unchanged
Close (Tab)	End and forget the session. A hidden live process needs a second Enter. For an exited session, removes its output.
Force kill (Tab)	For a hung program. Always asks, naming the terminal, even when visible: Enter confirms, Escape cancels. Kills the process group, discards its output, and shows the pane’s buffer. Unsaved work in the program is lost. Not offered for exited terminals.
Create (Tab)	Start a new terminal

Ending a program is always explicit: type exit in it, or choose Close or Force kill. Neither :close[!] nor any :quit… command ends a terminal, and every quit spelling, ! included, refuses while any terminal is running, pointing to :terminals.

Other commands:

Space t r (:terminal-rename <name>) names the active session.
:terminal-show <number|name> shows a specific session.
Duplicate names are refused as ambiguous.

Numbers and titles

A pane title reads [terminal #<number>] <name>.

The number is what :terminal-send, :terminal-show, and :terminal-session-directory accept. It is also in the list preview.
Only running terminals have numbers. A new terminal takes the lowest free number, and gives it up when its program exits or it is closed, so numbers stay small and are reused. Numbers never depend on list order.
Because a number can pass to a new terminal, it identifies what is running now. Do not record one in a macro or script expecting the same terminal later.
A retained exited terminal has no number: its title is [terminal] <name>, and it is reached from :terminals or the Finder by name. Action menu titles use the [terminal] <name> form too.
The name is the one you assigned, otherwise what the program calls itself: the title a shell sets from its prompt, or the program’s name until it sets one.
Scrolled back into history, the title adds ↑ and how far.
The active pane adds [insert] while keys go to the child.

Lifetime

Sessions live as long as the workspace-host process that owns them:

Survives	Does not survive
Normal detach	Force-stop
Client failure	Host replacement or crash
Switching workspaces	Logout or reboot
Reattaching	Machine failure

:detach leaves persistent terminal children running without signalling them. In ide and mux modes alike, quitting refuses while a terminal runs.