# Koshi 0.2.0 — Sessions and clients (/docs/v0.2/using) 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](/docs/v0.2/using/attach-and-detach). ## Start one [#start-one] ```bash 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 ``` `--headless` prints `[SESSION ID]: session-` and returns to the shell. Nothing is drawn. Attach to it later. ## What the session owns, and what your terminal owns [#what-the-session-owns-and-what-your-terminal-owns] | The session owns | Your terminal owns | | ------------------------------------------ | -------------------------------------- | | Tabs, panes, and their processes | Which tab it is looking at | | Scrollback and its size limits | Which pane is focused | | `TERM`, `COLORTERM`, and the default shell | Its theme and its keybindings | | `auto-close-session` | Its lock mode and mouse-selection mode | 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. Each terminal reads its own `koshi.kdl`, `themes/.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. See [Whose setting is it](/docs/v0.2/configuration#whose-setting-is-it). ## Names and ids [#names-and-ids] Every session, tab, pane, and client has a printed id. Sessions and tabs also have a generated name. ```text 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 [#see-what-is-running] Every list and inspect command takes `--format table` (default) or `--format json`. ```bash koshi list-sessions koshi list-tabs koshi list-panes koshi list-clients ``` ```bash koshi inspect session koshi inspect tab koshi inspect pane koshi inspect client ``` ## Targeting [#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 [#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. ## End one [#end-one] ```bash koshi kill-session # the only running session koshi kill-session # a named one ``` `kill-session` ends the session whatever else is attached to it, and skips the wait for programs to stop. Closing the last pane in a tab closes the tab. Closing the last tab ends the session. Leaving a session does not — that is [detaching](/docs/v0.2/using/attach-and-detach).