# Koshi 0.2.0 — Attach and detach (/docs/v0.2/using/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 [#leave-a-session]

Three things do the same job:

| How                                   | Where         |
| ------------------------------------- | ------------- |
| <kbd>\<C-q></kbd> — the quit shortcut | Inside a pane |
| `koshi detach`                        | Inside a pane |
| Closing the terminal window           | Anywhere      |

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

From outside koshi, name what to detach:

```bash
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 [#come-back]

```bash
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:

```text
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 [#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 [#start-a-session-with-nothing-attached]

```bash
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 [#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 [#when-an-empty-session-ends]

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

```bash
koshi kill-session <NAME_OR_ID>
```

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

```kdl title="koshi.kdl"
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.

<Callout>
  The session reads `auto-close-session` from the `koshi.kdl` it saw when it
  started. A terminal attaching later cannot change it from its own file. See
  [Whose setting is it](/docs/v0.2/configuration#whose-setting-is-it).
</Callout>

## Version compatibility [#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 [#commands]

| Command                            | Result                                              |
| ---------------------------------- | --------------------------------------------------- |
| `koshi list-sessions`              | List running sessions                               |
| `koshi attach [NAME_OR_ID]`        | Attach this terminal, or move it to another session |
| `koshi detach [CLIENT_OR_SESSION]` | Detach one terminal                                 |
| `koshi detach --all [NAME_OR_ID]`  | Detach every terminal of one session                |
| `koshi kill-session [NAME_OR_ID]`  | End the session                                     |
| `koshi --headless`                 | Start a session with nothing attached               |

Full flags and exit codes: [Session commands](/docs/v0.2/cli/sessions).