Sessions and clients

A session runs in a process of its own. It owns tabs, each tab owns a layout of panes, and each pane owns one process with its own terminal screen and scrollback.

A client is one terminal attached to that session. The client draws what the session sends and forwards your keys. It owns nothing but its view.

session (its own process)
├── tab
│   └── pane ── process, screen, scrollback
└── client ── one attached terminal

Because the session is not your terminal, closing the terminal does not close the work. See Attach and detach.

The client can sit on another machine. See Remote sessions.

Start one

koshi                  # one tab, one shell pane, this terminal attached
koshi --profile dev    # tabs and panes from profile/dev.kdl
koshi --headless       # a session with nothing attached; prints its id

# the same, reachable by the other users of this machine
koshi --headless --allow-other-users

--headless prints [SESSION ID]: session-<uuid> and returns to the shell. Nothing is drawn. Attach to it later.

What the session owns, and what your terminal owns

Two terminals on one session can therefore sit in different tabs, wear different colours, and use different keys. They cannot disagree about what is in a pane. See Your keys, your view.

Each terminal reads its own koshi.kdl, themes/<name>.kdl, and keybinding.kdl when it attaches. The session took its own copy of the session-owned settings when it started, so a terminal attaching later cannot change them. allow-other-users is the exception: the session re-reads it for every connection and every request, so turning it off shuts other users out without a restart. See Whose setting is it.

Names and ids

Every session, tab, pane, and client has a printed id. Sessions and tabs also have a generated name.

session-3f2a…    tab-91c4…    pane-77bd…    client-0e5a…

Anywhere a command takes NAME_OR_ID, either works. A value that reads as an id is always used as an id — it never falls back to a name lookup. A name that several targets share is refused, and the error lists every matching id. Pane and client flags take ids only.

See what is running

Every list and inspect command takes --format table (default) or --format json.

koshi list-sessions
koshi list-tabs
koshi list-panes
koshi list-clients

koshi list-sessions names each session's machine in its server column: local for a session on this machine, else the saved server it runs on.

koshi inspect session <NAME_OR_ID>
koshi inspect tab <NAME_OR_ID>
koshi inspect pane <PANE_ID>
koshi inspect client <CLIENT_ID>

Targeting

Inside koshi, a command with no target uses the current session, tab, pane, or client. Outside koshi, give a target unless exactly one session is running — in that case koshi uses it. Zero or several running sessions fail rather than guess.

Create commands print the ids they made: new-pane and run print one pane id, new-tab prints its tab id and root pane id, --headless prints its session id. Those ids are what you feed back into --pane, --tab, and --session.

Missed events

A client that misses an event resyncs from the session instead of drawing a stale view. You do not have to do anything; the view catches up.

Terminal images

Programs in a pane can draw images using Kitty, iTerm2, or Sixel. Each terminal selects its own supported protocol, so two terminals attached to one session may use different image output. Images keep their placement through scrolling, scrollback, resizing, and screen switches.

Set image-support #false to keep the text and the image placeholders without sending native image output. See Terminal images.

End one

koshi kill-session                  # the only running session
koshi kill-session <NAME_OR_ID>     # a named one

kill-session ends the session whatever else is attached to it, and skips the wait for programs to stop.