Panes
Open, move, focus, resize, stack, fullscreen, and close koshi panes from keys or the CLI.
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
| Keys | Where it opens |
|---|---|
| <C-p> h | Left |
| <C-p> j | Below |
| <C-p> k | Above |
| <C-p> l | Right |
| <C-p> n | layout.new-pane-direction |
| <C-p> s | In the focused pane's stack |
From a shell:
koshi new-pane --direction right
koshi new-pane --stacked
koshi run --direction down -- cargo watch -x testnew-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
| Keys | Result |
|---|---|
| <C-p> ←↓↑→ | Focus the nearby pane |
| <C-s> ←↓↑→ | Move one border one cell |
Focus is per client: two terminals attached to one session may look at different panes.
koshi focus-pane --pane <PANE_ID>
koshi resize-pane --pane <PANE_ID> --direction right --size 4A positive resize grows toward the direction. A negative value shrinks from that side.
Move a pane
Moving a pane changes its place in the layout; its process, terminal screen, and scrollback stay with it.
Press <C-p> m to preview a move. When this client shows a floating pane it did not pin, a chooser opens first: t moves a tiled pane and f a floating one. See Floating panes. Arrow keys choose a pane to swap with; Shift+Arrow chooses an edge to insert beside a pane or stack. s switches the target between that pane and its 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:
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:
koshi place-pane --pane <PANE_ID> --tab <TAB> --direction rightSee Pane commands and Moving pane keys.
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.
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.
version 2
pane {
gap 1
}The session owns the gap, so every terminal attached to it sees the same spacing.
Stack and fullscreen
<C-p> s 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.
Alt+f fills the tab with the focused pane. Press it again to restore the layout. Fullscreen belongs to the client that pressed it.
koshi toggle-pane-fullscreenClose a pane
<C-p> x closes the focused pane and its process tree.
koshi close-pane --pane <PANE_ID>
koshi close-pane --pane <PANE_ID> --forceClosing 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
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.
Your keys, your view
Each terminal attached to a koshi session resolves its own keybindings and owns its own focus, tab, zoom, scroll, and selection — so two people share one session without moving each other's screen.
Floating panes
Open panes above the tiled layout, float and dock existing panes, move, pin, resize, minimize, and restore them, and use the floating pane tray.