Floating panes

A floating pane sits above the tiled panes and belongs to no tab, so it stays in view when you switch tabs. A session holds at most 12 floating panes.

The pane, its program, and its scrollback belong to the session. Where it sits, whether it is pinned, and whether it is minimized belong to each attached terminal: moving or minimizing a floating pane on your screen leaves every other terminal's screen as it was.

Open and float

<C-p> f opens the pane at 60% of each axis of the pane area. The shell starts in the working directory of the focused pane. Your terminal shows the new pane and gives it your keys; every other terminal holds it minimized.

<C-p> u on a tiled or stacked pane floats it where you see it, keeping its program and scrollback, its top-left cell, and its size, each axis cut to 90% of the smallest pane area of the attached terminals. The other panes of its tab fill the space. If it was the only pane of its tab, the tab closes.

<C-p> u on a floating pane docks it into your active tab, beside the smallest pane, group, or tab span under the pane's center cell, on the edge nearest that cell. A tab with no room refuses with tab <name> has no room for another pane.

The last tiled pane of the session's only tab cannot float, and a 13th floating pane is refused with a session holds at most 12 floating panes.

From a shell:

koshi new-pane --floating
koshi run --floating --cols 80 --rows 60% -- htop
koshi undock-pane --pane <PANE_ID>
koshi dock-pane --pane <PANE_ID> --tab <TAB> --direction right

See Pane commands for every flag.

Focus

The steps follow the order the panes became floating and wrap at the ends. A minimized pane is shown again. From a tiled pane, Tab lands on the first floating pane and Shift+Tab on the last. The prefix stays open, so each further Tab takes one more step; Esc closes it.

The titlebar

Each floating pane has a titlebar row:

A pinned pane does not move, and resizes from its right and bottom borders only. <C-p> i pins or unpins the focused floating pane.

Mouse

A floating pane takes the mouse on every cell it covers. A wheel notch on any of those cells, the titlebar and border included, scrolls that pane.

• Drag the grab handle to move the pane. It stays inside the pane area, and the move is sent when you release. Esc during the drag cancels it.
• Drag a border to resize the pane, up to the edge of the pane area on that side. A drag on a corner moves the two borders that meet there.
• A press on the titlebar, the grab handle, or the border focuses the pane and shows it above your other floating panes.

Move with the keyboard

<C-p> m opens a chooser when your terminal shows a floating pane you did not pin. f opens floating pane move mode (MOVE FLOAT), and t the tiled pane move preview.

The mode selects the focused floating pane, or the front-most one when a tiled pane is focused, and never a pinned or minimized pane. A drag on a pane's content or grab handle also moves it. By default the mode stays open after a move; stay-in-pane-placement-mode-after-placement #false closes it.

The tray

The tab bar shows the tray button ⧉. <C-p> w or a click on it opens the tray (TRAY), which lists every floating pane of the session as a numbered tile, in the order the panes became floating, then a + new tile.

A lit tile is a pane your terminal shows; a gray tile is one you minimized.

A click on a tile does what Enter does. The tray's titlebar shows the full title of the selected tile and a minimize all or restore all label. A click outside the tray closes it. Opening, minimizing, and restoring change only your screen.

Minimize and restore

A minimized pane keeps its program running. Show it again with <C-p> Tab, from the tray, or from a shell:

koshi minimize-pane --pane <PANE_ID>
koshi restore-pane --all

Other actions

These actions have no default key and can be bound in keybinding.kdl or run with koshi actions run:

Small terminals

A terminal whose pane area is smaller than 5x6, or that shows Terminal too small — enlarge window, cannot draw floating panes. It holds every floating pane minimized, and floating-pane focus keys are refused with no floating pane can be drawn on this client.