# Koshi 0.5.0 — Panes (/docs/v0.5/using/panes)



Each pane owns one process, terminal screen, and scrollback buffer. Splitting a
pane keeps the existing pane and places a new one beside it. The session owns
the panes, so every attached terminal sees the same ones.

## Open a pane [#open-a-pane]

| Keys                           | Where it opens              |
| ------------------------------ | --------------------------- |
| <kbd>\<C-p></kbd> <kbd>h</kbd> | Left                        |
| <kbd>\<C-p></kbd> <kbd>j</kbd> | Below                       |
| <kbd>\<C-p></kbd> <kbd>k</kbd> | Above                       |
| <kbd>\<C-p></kbd> <kbd>l</kbd> | Right                       |
| <kbd>\<C-p></kbd> <kbd>n</kbd> | `layout.new-pane-direction` |
| <kbd>\<C-p></kbd> <kbd>s</kbd> | In the focused pane's stack |

From a shell:

```bash
koshi new-pane --direction right
koshi new-pane --stacked
koshi run --direction down -- cargo watch -x test
```

`new-pane` starts the default shell. `run` starts the command after `--`.
Both print the new pane id. Omit a target inside koshi to split the current
pane; outside koshi, pass `--pane`, `--tab`, or `--session` unless exactly one
session is running.

A shell pane inherits the working directory of the pane it splits. A command
pane runs the command and arguments you gave after `--`.

## Focus and resize [#focus-and-resize]

| Keys                              | Result                   |
| --------------------------------- | ------------------------ |
| <kbd>\<C-p></kbd> <kbd>←↓↑→</kbd> | Focus the nearby pane    |
| <kbd>\<C-s></kbd> <kbd>←↓↑→</kbd> | Move one border one cell |

Focus is per client: two terminals attached to one session may look at
different panes.

```bash
koshi focus-pane --pane <PANE_ID>
koshi resize-pane --pane <PANE_ID> --direction right --size 4
```

A positive resize grows toward the direction. A negative value shrinks from
that side.

## Move a pane [#move-a-pane]

Moving a pane changes its place in the layout; its process, terminal screen,
and scrollback stay with it.

Press <kbd>\<C-p></kbd> <kbd>m</kbd> to preview a move. Arrow keys choose a
pane to swap with; Shift+Arrow chooses an edge to insert beside a pane or
stack. Space cycles the available split spans. Tab and Shift+Tab preview
another visible tab. Press Enter to accept the move or Escape to cancel it.

Only the client that started the move sees the preview. All attached clients
see the new layout after it is accepted. The move stays active after a move by
default, so you can move another pane; Escape returns to the prior input mode.

You can also move panes with the mouse. In normal mode, drag a pane's handle
onto another pane to swap the two. In the move mode, dragging a pane onto
another also swaps them, and holding Shift when you start the drag inserts it
beside the target instead. koshi asks the terminal to send Shift with mouse
events during the move mode; a terminal that keeps Shift for its own text
selection cannot insert by mouse, and Shift+Arrow selects an insertion edge
from the keyboard. Outside the move mode, Shift+drag over pane content selects
text.

From a shell, `move-pane` swaps a pane with a visible neighbor right away:

```bash
koshi move-pane --direction right
koshi move-pane --direction left --pane <PANE_ID>
```

To move an existing pane into another tab's tiled layout, use `place-pane`:

```bash
koshi place-pane --pane <PANE_ID> --tab <TAB> --direction right
```

See [Pane commands](/docs/v0.5/cli/panes) and
[Moving pane keys](/docs/v0.5/keybindings/default-keymap).

## Size when several terminals watch [#size-when-several-terminals-watch]

Every client viewing one tab shares one set of sizes. The tab solves against
the smallest viewing terminal on each axis, minus the top tab bar row and the
bottom hint row. Two clients on one tab, one 80x24 and one 120x40, both get a
viewport of 80x22.

What stays per client is the view: one client tiled and one with a pane
fullscreen give that tab two sets of rectangles. Read them with
[`koshi debug dump-layout`](/docs/v0.5/cli/debug).

## Leave gaps between panes [#leave-gaps-between-panes]

Set `pane.gap` in `koshi.kdl` to leave blank cells between panes that meet along
a horizontal or vertical split. Stacked panes stay contiguous, and mouse
border dragging still works across a gap.

```kdl title="koshi.kdl"
version 2

pane {
    gap 1
}
```

The session owns the gap, so every terminal attached to it sees the same
spacing.

## Stack and fullscreen [#stack-and-fullscreen]

<kbd>\<C-p></kbd> <kbd>s</kbd> or `--stacked` adds a pane to the focused pane's stack. Stack members share one
rectangle; one is expanded and the others appear as one-row headers.

<kbd>Alt+f</kbd> fills the tab with the focused pane. Press it again to restore
the layout. Fullscreen belongs to the client that pressed it.

```bash
koshi toggle-pane-fullscreen
```

## Close a pane [#close-a-pane]

<kbd>\<C-p></kbd> <kbd>x</kbd> closes the focused pane and its process
tree.

```bash
koshi close-pane --pane <PANE_ID>
koshi close-pane --pane <PANE_ID> --force
```

Closing a pane promotes its sibling into the freed space. Closing the last pane
closes its tab; closing the last tab ends the session.

## Send input [#send-input]

```bash
koshi input --pane <PANE_ID> "cargo test"
koshi input --pane <PANE_ID> --no-enter "git status"
```

`input` types text into a pane and presses Enter by default. `--no-enter`
leaves it at the prompt.