# Koshi 0.6.0 — koshi at a glance (/docs/v0.6/overview)



Everything koshi is, on one page: the words it uses, the keys it ships with,
the commands you will type, and the three properties that shape how it works.

Read it start to finish in a few minutes, or jump to the part you need.

## koshi's vocabulary [#koshis-vocabulary]

| Term              | What it means in koshi                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| **Session**       | A process of its own that owns tabs. It keeps running after every terminal leaves.                          |
| **Client**        | One terminal attached to a session. Several can attach at once.                                             |
| **Tab**           | Holds one layout of panes. Created, closed, moved, and switched.                                            |
| **Pane**          | One process, with its own terminal screen and scrollback.                                                   |
| **Floating pane** | A pane above the tiled panes that belongs to no tab. Each client places, pins, and minimizes it for itself. |
| **Leader**        | The key a shortcut starts with. <kbd>Ctrl</kbd> by default, and configurable.                               |
| **Profile**       | A saved layout of tabs, panes, commands, directories, and environment values.                               |

## The default keys [#the-default-keys]

The default leader is the Ctrl modifier run, so `<leader>p` is
<kbd>\<C-p></kbd>.

| Keys                                          | Result                                     |
| --------------------------------------------- | ------------------------------------------ |
| <kbd>\<C-p></kbd> <kbd>h j k l</kbd>          | Open a pane left, down, up, right          |
| <kbd>\<C-p></kbd> <kbd>n</kbd>                | Open a pane in the configured direction    |
| <kbd>\<C-p></kbd> <kbd>s</kbd>                | Open a pane in the focused pane's stack    |
| <kbd>\<C-p></kbd> <kbd>f</kbd>                | Open a floating pane                       |
| <kbd>\<C-p></kbd> <kbd>u</kbd>                | Float the focused pane, or dock it         |
| <kbd>\<C-p></kbd> <kbd>w</kbd>                | Open the floating pane tray                |
| <kbd>\<C-p></kbd> <kbd>m</kbd>                | Preview a move for an existing pane        |
| <kbd>\<C-p></kbd> <kbd>x</kbd>                | Close the pane and its process tree        |
| <kbd>\<C-p></kbd> <kbd>←↓↑→</kbd>             | Focus a nearby pane                        |
| <kbd>\<C-s></kbd> <kbd>←↓↑→</kbd>             | Move a pane border one cell                |
| <kbd>\<C-t></kbd> <kbd>n</kbd> / <kbd>x</kbd> | Open / close a tab                         |
| <kbd>Tab</kbd> / <kbd>Shift+Tab</kbd>         | Next / previous tab                        |
| <kbd>Alt+f</kbd>                              | Fullscreen the focused pane, and back      |
| <kbd>Alt+n</kbd>                              | Open the notification center               |
| <kbd>\<C-l></kbd>                             | Lock input — every key goes to the program |
| <kbd>\<C-g></kbd>                             | Toggle mouse-selection mode                |
| <kbd>\<C-q></kbd>                             | Leave the session, which keeps running     |

Rebind any of it in `keybinding.kdl`. See
[How keys work](/docs/v0.6/keybindings).

In move mode, arrows choose a pane to swap with and Shift+Arrow chooses where
to insert beside a pane or stack. Enter accepts the preview; Escape cancels
it. Only the client making the move sees the preview. See
[Panes](/docs/v0.6/using/panes).

## Detach and attach [#detach-and-attach]

```bash
koshi                        # start a session, attach this terminal
koshi detach                 # leave it running
koshi list-sessions          # what is still running
koshi attach                 # pick one and rejoin
koshi kill-session <NAME>    # end it for good
koshi --headless             # start one with nothing attached
```

## Properties to know [#properties-to-know]

These properties shape almost everything else in the documentation.

### Your keybindings are resolved on your machine [#your-keybindings-are-resolved-on-your-machine]

The terminal you sit at reads your own `keybinding.kdl` and decides what each
key means. It sends the session the **action name** —
`core:new-pane-right` — never the key. A session on another machine works the
same way, so your shortcuts follow you there and you never edit a keybinding
file on the far end.

See [Your keys, your view](/docs/v0.6/using/per-client).

### Every attached terminal keeps its own view [#every-attached-terminal-keeps-its-own-view]

The focused pane, the active tab, the fullscreened pane, the scroll position,
the text selection, and the lock mode belong to the terminal, not the session.
Two people attach to one session, sit in different tabs, and type into
different panes without moving each other's screen.

### Floating panes belong to the session, their place to you [#floating-panes-belong-to-the-session-their-place-to-you]

A floating pane sits above the tiled panes of every tab. Its program and
scrollback belong to the session; where it sits, whether it is pinned, and
whether it is minimized belong to each terminal. The tray (<kbd>\<C-p></kbd>
<kbd>w</kbd>) lists them. See [Floating panes](/docs/v0.6/using/floating-panes).

### koshi's messages go to the notification center [#koshis-messages-go-to-the-notification-center]

A pane killed by a signal, a config warning, or a refused key shows as a short
toast and stays in the notification center (<kbd>Alt+n</kbd>). See
[Notifications](/docs/v0.6/using/notifications).

### Terminal images use each terminal's protocol [#terminal-images-use-each-terminals-protocol]

A pane can draw Kitty, iTerm2, or Sixel images. Each attached terminal probes its
own capabilities and chooses the protocol it supports. Images keep their cell
placement through scrolling, resizing, and screen switches. A terminal without
image support shows `terminal image unavailable` in the covered cells.

See [Terminal images](/docs/v0.6/using/images).

### Terminal input keeps key details [#terminal-input-keeps-key-details]

Koshi forwards key presses, repeats, releases, text, and modifiers to pane
programs with the Kitty keyboard protocol. Terminal programs can also set
horizontal margins and origin mode. See
[Keyboard input](/docs/v0.6/using/terminal-input).

### Remote sessions are built in [#remote-sessions-are-built-in]

```bash
koshi share grant alice                  # on the machine holding the sessions
koshi attach --remote work S-quiet-heron   # from anywhere else
```

TLS 1.3, a certificate fingerprint checked before the secret is sent, and an
access token you scope to one session or all of them and revoke at any time. A
dropped link dials again for up to two minutes and restores your tabs, focus,
and scroll position.

See [Remote sessions](/docs/v0.6/remote).

## Configuration is KDL [#configuration-is-kdl]

Four optional files, each declaring a schema version. Version 2 is current;
version 1 files migrate automatically before a session server or router reads
them:

| File                 | Holds                           |
| -------------------- | ------------------------------- |
| `koshi.kdl`          | App settings                    |
| `themes/<name>.kdl`  | Interface colours               |
| `keybinding.kdl`     | Keys and the modes they live in |
| `profile/<name>.kdl` | A saved layout                  |

```bash
koshi config check                 # validate every file
koshi config explain <KEY>         # what one setting does
koshi keys conflicts               # clashes and unreachable shortcuts
koshi doctor                       # rate the whole installation
```

Nothing is required — with no files present, built-in defaults apply. See
[Configuration](/docs/v0.6/configuration).

## Scripting it [#scripting-it]

Every pane, tab, input, focus, lock, and session operation has a shell command,
and every list and inspect command takes `--format json`:

```bash
pane=$(koshi new-pane --direction right | awk '{print $NF}')
koshi input --pane "$pane" "cargo watch -x test"
koshi list-panes --format json
```

See [CLI conventions](/docs/v0.6/cli).

## What you get in the box [#what-you-get-in-the-box]

Split and stacked panes, pane gaps, fullscreen, moving existing panes, keyboard
and mouse resize, tabs, per-pane scrollback, true colour, CJK and emoji,
terminal images through Kitty,
iTerm2, and Sixel, OSC 52 clipboard copy over SSH, 25 themes, saved profiles,
per-session logging, remote sessions, same-machine sharing, in-place updates,
and `koshi doctor`. Linux, macOS, and Windows, on
x86-64 and ARM64. MIT licensed.

## Next [#next]

<Cards>
  <Card title="Installation" href="/docs/v0.6/installation" description="Homebrew, Scoop, the release script, or from source." />

  <Card title="Quick start" href="/docs/v0.6/quick-start" description="One session, one split, one tab, and back out again." />

  <Card title="Panes" href="/docs/v0.6/using/panes" description="Open, move, focus, resize, stack, and close panes." />

  <Card title="FAQ" href="/docs/v0.6/faq" description="The questions people ask before installing it." />

  <Card title="Configuration" href="/docs/v0.6/configuration" description="The four KDL files, field by field." />

  <Card title="Terminal input" href="/docs/v0.6/using/terminal-input" description="Key details, horizontal margins, and origin mode." />

  <Card title="Terminal images" href="/docs/v0.6/using/images" description="The three image protocols and the image-support setting." />
</Cards>