Pane commands
Create, run, float, dock, move, pin, minimize, close, resize, focus, scroll, fullscreen, and write to panes from any shell.
Inside koshi, omitted targets use the current session, tab, pane, or client. Outside koshi, pass a target unless exactly one running session can be chosen.
Without --pane, close-pane, resize-pane, scroll-pane, and input act
on the pane the command runs in, or, outside koshi, on the pane that takes the
client's keys: its focused floating pane, else its focused pane in its tab.
These verbs take --remote <SERVER> to act on a session on another machine.
See Remote commands.
new-pane
Open a shell pane:
koshi new-pane
koshi new-pane --direction left
koshi new-pane --stacked
koshi new-pane --floatingMain flags:
| Flag | Meaning |
|---|---|
--direction right|down|left|up | Open the new pane beside its target |
--stacked | Add it to the target's stack |
--pane <PANE_ID> | Split this pane |
--tab <NAME_OR_ID> | Create inside this tab |
--session <NAME_OR_ID> | Choose the session |
--client <CLIENT_ID> | The client that shows and focuses the new pane. Outside koshi with no --pane or --tab, the new pane splits this client's focused pane |
--floating | Open the pane floating above the tiled panes; see Floating panes |
--direction and --stacked are alternatives. The command prints one pane id.
The new pane starts in the current working directory of the pane it splits from, with the environment the session process started with plus koshi's own variables.
Outside koshi with no --pane, --tab, or --client, the new pane splits the
focused pane of the session's only attached client. With several clients
attached, the command fails with several clients are attached; name the target client. Inside a floating pane, new-pane without --pane is refused; use
--floating, or dock the pane first.
run
Open a pane running one command:
koshi run -- htop
koshi run --direction down -- cargo watch -x testPlacement flags match new-pane, --floating included. Everything after
-- is the command and its arguments. The command prints one pane id.
close-pane
koshi close-pane
koshi close-pane --pane <PANE_ID>
koshi close-pane --pane <PANE_ID> --forceClosing the last pane closes its tab. --force kills the pane's program at once
instead of asking it to stop first.
resize-pane
koshi resize-pane --direction right
koshi resize-pane --direction left --size 4 --pane <PANE_ID>
koshi resize-pane --direction right --size -2Directions are right, down, left, and up. A positive size grows toward
that direction; a negative size shrinks from that side. The border moves up to
--size cells, as far as minimum sizes allow; a border that cannot move one
cell is refused and nothing changes.
On a floating pane, --client names the client whose view keeps the opposite
edge in place, and the pane grows only up to that client's pane area edge.
With several clients attached and no --client, the resize is refused.
focus-pane
koshi focus-pane --pane <PANE_ID>
koshi focus-pane --pane <PANE_ID> --client <CLIENT_ID>
koshi focus-pane --next-floating
koshi focus-pane --previous-floatingFocus belongs to a client. --client chooses which attached terminal moves.
--pane also takes a floating pane, minimized or not: it shows above the
client's other floating panes and takes its keys. --next-floating and
--previous-floating show and focus the next or previous floating pane, in
the order the panes became floating, wrapping at the ends.
move-pane
Swap a tiled pane with its visible neighbor immediately, without a preview or confirmation:
koshi move-pane --direction right
koshi move-pane --direction left --pane <PANE_ID>| Flag | Meaning |
|---|---|
--direction right|down|left|up | Choose the visible neighbor in this direction |
--pane <PANE_ID> | Pane to move; defaults to the focused pane |
To move a floating pane on one client's screen, give --x and --y instead;
see Floating panes.
place-pane
Insert a pane into a tab's tiled layout, on one side of the whole tab or into the stack of another pane. A floating pane docks.
koshi place-pane --pane <PANE_ID> --tab <TAB> --direction right
koshi place-pane --pane <PANE_ID> --stack-onto <PANE_ID>| Flag | Meaning |
|---|---|
--pane <PANE_ID> | Pane to place; defaults to the pane this command runs in, else the focused pane |
--tab <TAB> | Destination tab, by id or name |
--direction right|down|left|up | Side of the destination tab where the pane lands |
--stack-onto <PANE_ID> | Tiled pane whose stack the pane joins as the open member; a pane in no stack forms a new stack with it |
--client <CLIENT_ID> | Client whose view sizes the destination layout |
scroll-pane
koshi scroll-pane --lines 10
koshi scroll-pane --lines -10 --pane <PANE_ID>
koshi scroll-pane --lines 5 --client <CLIENT_ID>Scrolls one client's view of a pane. A positive count moves toward history; a
negative count moves toward the newest output. --pane defaults to the
client's focused pane, and --client defaults to the issuing client.
toggle-pane-fullscreen
koshi toggle-pane-fullscreen
koshi toggle-pane-fullscreen --client <CLIENT_ID>Fill the current tab with its focused pane, or restore the prior layout. The
fullscreen view belongs to one client; --client names which one. A floating
pane cannot go fullscreen; inside one, or outside koshi while one takes the
client's keys, the command is refused.
input
koshi input --pane <PANE_ID> "cargo test"
koshi input --pane <PANE_ID> --no-enter "git status"Text is followed by Enter unless --no-enter is present.
Floating panes
A floating pane sits above the tiled panes and belongs to no tab. A session holds at most 12. Where it sits, whether it is pinned, and whether it is minimized belong to each client; the pane and its program belong to the session.
Open one
koshi new-pane --floating
koshi run --floating --cols 80 --rows 60% --x 4 --y 2 -- htop| Flag | Meaning |
|---|---|
--floating | Open the pane floating. Refused with --direction, --stacked, --pane, and --tab |
--cols <COLUMNS> | Width: columns (80) or a percent of the pane area (60%); needs --rows. Default 60% |
--rows <ROWS> | Height: rows (20) or a percent (60%); needs --cols. Default 60% |
--x <COLUMN> | Column of the top-left cell, from the left edge of the pane area; needs --y |
--y <ROW> | Row of the top-left cell, from the top edge of the pane area; needs --x |
--pinned | Pin the pane on the client that shows it |
Each axis is cut to 90% of the smallest pane area of the attached clients:
--cols 100% --rows 100% on an 80x22 pane area gives 72x19.
The client --client names, else the issuing client, else the session's only
attached client, shows the pane and gives it its keys. Every other client holds
it minimized. A client whose pane area is smaller than 5x6, or that shows
Terminal too small — enlarge window, cannot draw floating panes and holds it
minimized too.
Float and dock
koshi undock-pane
koshi undock-pane --pane <PANE_ID> --x 10 --y 2
koshi dock-pane
koshi dock-pane --pane <PANE_ID> --tab <TAB> --direction down
koshi dock-pane --pane <PANE_ID> --stack-onto <PANE_ID>undock-pane floats a tiled or stacked pane where the client draws it,
keeping its top-left cell and size (each axis cut to 90% as above). --x and
--y move its top-left cell. The other panes of its tab fill the space. The
last tiled pane of the session's only tab cannot be undocked.
dock-pane puts a floating pane into a tab's tiled layout, on the side
--direction names (right by default), or into the stack of the pane
--stack-onto names. Without --tab, it uses the tab the --client client
views, else the tab of the tiled pane the command runs in, else the tab the
issuing client or the session's only attached client views, else the
session's only tab. A tab with no room refuses with
tab <name> has no room for another pane.
| Flag | undock-pane | dock-pane |
|---|---|---|
--pane <PANE_ID> | Pane to float; defaults to the pane this command runs in, else the focused pane | Floating pane to dock; same default |
--tab <TAB> | — | Destination tab |
--direction | — | Side of the destination tab; default right |
--stack-onto <PANE_ID> | — | Tiled pane whose stack the pane joins |
--x, --y | Top-left cell | — |
--client <CLIENT_ID> | Client that shows and focuses the floating pane | Client that moves to the destination tab |
Move, pin, minimize, restore
koshi move-pane --pane <PANE_ID> --x 20 --y 3
koshi pin-pane
koshi unpin-pane --pane <PANE_ID>
koshi minimize-pane
koshi minimize-pane --all
koshi restore-pane --pane <PANE_ID>
koshi restore-pane --allThese change one client's screen; --client names which, defaulting to the
issuing client, else the session's only attached one. Without --pane, they
act on the pane they run in, or from outside koshi on the client's focused
floating pane.
move-pane --x --ymoves the pane's top-left cell.--paneis required. A pinned pane is refused with<pane> is pinned; unpin it to move it.pin-panekeeps the pane at its top-left cell: that client's moves and left or top edge resizes are refused.unpin-panereleases it; it stays where it is.minimize-panehides the pane on that client; its program keeps running.--allminimizes every floating pane the client shows.restore-paneshows a minimized pane again.--allrestores every floating pane the client minimized. The last pane restored is drawn on top and focused.
scroll-pane --pane on a floating pane the client minimized is refused with
<pane> is minimized; restore it first.