Attach and detach

A session runs in its own process, so a terminal can leave it and come back. Every pane keeps running in between.

Leave a session

Three things do the same job:

The session keeps running with its panes untouched. Quit never ends a session on its own.

From outside koshi, name what to detach:

koshi detach client-0e5a…        # one attached terminal
koshi detach session-3f2a…       # that session's client
koshi detach amber-fox           # the same, by session name
koshi detach --all amber-fox     # every terminal of that session

Come back

koshi attach amber-fox                # by name
koshi attach session-3f2a…            # by id
koshi attach --remote work web        # a session on another machine

With no argument, koshi lists the sessions running for this user and the sessions on every saved server that answered, numbers them, and reads your answer. A session on a saved server carries (remote: <server>):

koshi attach
1) amber-fox session-3f2a…
2) quiet-heron session-91c4… (remote: work)
attach to which session? [1-2]

A listing of exactly one session, on this machine, is attached without asking. Every other listing asks, one session on a saved server included, whose prompt reads attach to which session? [1].

Attaching to a machine you have not saved yet is Remote sessions.

Move a terminal between sessions

Run koshi attach <session> inside a koshi pane and the terminal you are sitting at moves to that session. It leaves the one it was in, which counts as leaving for auto-close-session.

Start a session with nothing attached

koshi --headless
[SESSION ID]: session-3f2a…

Nothing is drawn and the shell comes straight back. Use the printed id to attach, or to drive the session with the ordinary commands.

Several terminals, one session

More than one terminal can attach to a session at once. Each keeps its own:

• focused pane, current tab, and fullscreened pane;
• scroll position and text selection;
• theme, keybindings, and lock mode;
• mouse-selection mode.

They share the panes, the processes, and the scrollback. A pane's size is shared too: a tab solves against the smallest terminal viewing it on each axis.

A terminal that misses an event resyncs instead of drawing a stale view.

Your keys are resolved on your own machine and reach the session as action names, never as keys. See Your keys, your view.

When an empty session ends

By default it does not. A session with no terminal attached keeps running until you end it:

koshi kill-session <NAME_OR_ID>

Set auto-close-session #true in koshi.kdl to end a session once its last terminal leaves:

version 1
auto-close-session #true

koshi counts the terminals after the one that left is gone. If any are still attached, the session keeps running; only an empty session ends.

Ending it asks every program in the session to stop, waits up to three seconds, then kills whatever has not exited — long enough for a shell to write its history and an editor its swap file. On Windows a program cannot be asked to stop, so everything is killed at once. koshi kill-session skips the wait either way.

Version compatibility

The terminal and the session speak a protocol with a version. Each build speaks a range of versions. When the two ranges do not overlap, the connection is refused with an error naming what each side speaks — nothing is drawn and nothing is changed.

It matters when you upgrade koshi while a session started by the old binary is still running, and when the two machines of a remote connection run different releases. Install the same koshi release on both sides.

Since 0.3.0, koshi update moves the running sessions for you: each session replaces its own program while keeping its panes, the programs in them, and their scrollback. A session that refuses the restart is named on standard error and keeps the old build — end it and start it again. koshi server-version shows which sessions moved. See Update.

Commands

Full flags and exit codes: Session commands.