# koshi at a glance (/docs/v0.4/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.                          |
| **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>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>\<C-l></kbd>                             | Lock input — every key goes to the program |
| <kbd>\<C-q></kbd>                             | Leave the session, which keeps running     |

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

## 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
```

## Three properties to know [#three-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.4/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.

### 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.4/using/images).

### 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 quiet-heron   # from anywhere else
```

TLS, with the server's certificate pinned on the first connection, 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.4/remote).

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

Four optional files, each declaring `version 1`:

| 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.4/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.4/cli).

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

Split and stacked panes, pane gaps, fullscreen, 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.4/installation" description="Homebrew, Scoop, the release script, or from source." />

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

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

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

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