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 S-amber-fox           # the same, by session name
koshi detach --all S-amber-fox     # every terminal of that session

Come back

koshi attach S-amber-fox           # by name
koshi attach session-3f2a…       # by id

With no argument and several sessions running, koshi numbers them and reads your answer:

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

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. Commands that open panes or tabs, such as new-pane, run, and new-tab, need a terminal attached to the session.

Several terminals, one session

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

• focused pane and current tab;
• 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.

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.

koshi 0.2.0 speaks protocol version 2 only. koshi 0.1.0 speaks version 1, so the two cannot talk to each other in either direction.

That matters when you upgrade koshi while a session started by the old binary is still running: the old session keeps running old code, and the new koshi cannot join it. End your sessions before upgrading, then start fresh ones with the new binary.

Commands

Full flags and exit codes: Session commands.