# Quick start (/docs/v0.4/quick-start)



## Open a session [#open-a-session]

```bash
koshi
```

That gives you one tab with one shell pane. The bar at the top lists tabs; the
bar at the bottom shows key hints once a shortcut is pending.

## Split a pane [#split-a-pane]

The default leader is <kbd>Ctrl</kbd>. Press the leader chord, then the
direction:

| Keys                           | Result                                  |
| ------------------------------ | --------------------------------------- |
| <kbd>\<C-p></kbd> <kbd>l</kbd> | Open a pane to the right                |
| <kbd>\<C-p></kbd> <kbd>h</kbd> | Open a pane to the left                 |
| <kbd>\<C-p></kbd> <kbd>j</kbd> | Open a pane below                       |
| <kbd>\<C-p></kbd> <kbd>k</kbd> | Open a pane above                       |
| <kbd>\<C-p></kbd> <kbd>n</kbd> | Open a pane in the configured direction |

A new pane inherits the working directory of the pane you split from.

## Move around and resize [#move-around-and-resize]

| Keys                              | Result                                       |
| --------------------------------- | -------------------------------------------- |
| <kbd>\<C-p></kbd> <kbd>←↓↑→</kbd> | Focus a nearby pane                          |
| <kbd>\<C-s></kbd> <kbd>←↓↑→</kbd> | Move the pane border one cell                |
| <kbd>Alt+f</kbd>                  | Fill the tab with the focused pane, and back |
| <kbd>\<C-p></kbd> <kbd>x</kbd>    | Close the pane and its process tree          |

## Add a tab [#add-a-tab]

| Keys                                  | Result              |
| ------------------------------------- | ------------------- |
| <kbd>\<C-t></kbd> <kbd>n</kbd>        | Open a tab          |
| <kbd>Tab</kbd> / <kbd>Shift+Tab</kbd> | Next / previous tab |
| <kbd>\<C-t></kbd> <kbd>x</kbd>        | Close the tab       |

## Leave and come back [#leave-and-come-back]

<kbd>\<C-q></kbd> takes your terminal out of the session. It does not end
the session — every pane keeps running.

```bash
koshi list-sessions      # what is still running
koshi attach             # pick one and rejoin it
```

`koshi detach` from inside a pane does the same as the quit shortcut. See
[Attach and detach](/docs/v0.4/using/attach-and-detach).

## End a session for good [#end-a-session-for-good]

```bash
koshi kill-session       # the only running session
```

Or set `auto-close-session #true` in `koshi.kdl` to end each session once its
last terminal leaves.

## Get out of the way [#get-out-of-the-way]

When a program needs the keys koshi is holding, lock input with
<kbd>\<C-l></kbd>. Every keystroke then goes straight to the program until
you unlock.

## See the live keymap [#see-the-live-keymap]

```bash
koshi keys list
koshi actions list
```

<Callout>
  Nothing above needs a config file. When you want to change it, start at
  [Configuration](/docs/v0.4/configuration).
</Callout>

## Check the installation [#check-the-installation]

```bash
koshi doctor
```

One row per check, each rated `ok`, `warn`, or `fail`. See
[Doctor](/docs/v0.4/cli/doctor).

## Attach from another machine [#attach-from-another-machine]

On the machine holding the sessions, name a listen address in `koshi.kdl` and
grant a token:

```kdl title="koshi.kdl"
version 1
remote-listen "0.0.0.0:7654"
```

```bash
koshi share grant alice     # answer y to open the port; copy the token
```

From the machine you sit at:

```bash
export KOSHI_REMOTE_SECRET='<the secret the grant printed>'
koshi attach --remote laptop.local:7654 --save-as work quiet-heron
```

Full walkthrough: [Setup](/docs/v0.4/remote/setup).

## Start from a saved layout [#start-from-a-saved-layout]

Write a profile once and open the whole desk with one command:

```bash
koshi --profile dev
```

See [Profiles](/docs/v0.4/configuration/profiles).