Koshi 0.6.0 — Actions

A binding names a full action reference such as core:new-pane-right. Run:

koshi actions list
koshi actions explain core:new-pane-right
koshi actions run core:toggle-notification-center

list shows every action with its internal command, scope, and the shell command that runs it (cli_invocation). explain shows one action's description, scope, accepted targets, and related CLI command.

run runs one action in a running session, as a key bound to it runs it. It takes a bare name (next-tab) or a full name (core:next-tab), and --client names the client it acts for. An action that changes one client's screen runs in that client; an action that belongs to one input mode is refused in any other mode. run also takes --remote.

Pane actions

Action	Result
`core:new-pane`	Split the focused pane and start a shell in the new one
`core:new-pane-left`	Split the focused pane and open the new one on the left
`core:new-pane-down`	Split the focused pane and open the new one below
`core:new-pane-up`	Split the focused pane and open the new one above
`core:new-pane-right`	Split the focused pane and open the new one on the right
`core:new-pane-stacked`	Add a new pane to the focused pane's stack, sharing its space
`core:run`	Spawn a command in a new pane
`core:close-pane`	Close the focused pane
`core:close-pane-tree`	Close the focused pane and kill every process it started
`core:resize-pane`	Grow or shrink the focused pane along one edge
`core:resize-pane-left`	Move the focused pane's border one cell to the left
`core:resize-pane-down`	Move the focused pane's border one cell down
`core:resize-pane-up`	Move the focused pane's border one cell up
`core:resize-pane-right`	Move the focused pane's border one cell to the right
`core:focus-pane`	Move the issuing client's focus to a pane
`core:focus-pane-left`	Move the issuing client's focus to the pane on the left
`core:focus-pane-down`	Move the issuing client's focus to the pane below
`core:focus-pane-up`	Move the issuing client's focus to the pane above
`core:focus-pane-right`	Move the issuing client's focus to the pane on the right
`core:scroll-pane`	Scroll a pane's view by a chosen number of lines
`core:scroll-pane-up`	Scroll the focused pane's view toward its history
`core:scroll-pane-down`	Scroll the focused pane's view toward live output
`core:move-pane`	Swap a pane with its visible neighbor in one direction and commit the swap at once
`core:place-pane`	Put a pane into a tab's tiled layout, beside a pane or into its stack; a floating pane docks
`core:toggle-pane-fullscreen`	Toggle fullscreen for the focused pane
`core:write-to-pane`	Send text to a pane's shell, as if it had been typed there

Floating pane actions

Action	Result
`core:new-pane-floating`	Open a new floating pane above the tiled panes and focus it on the issuing client's screen
`core:toggle-pane-floating`	Float the pane that takes the input where it is drawn, or dock a floating one beside the tiled pane under its center
`core:undock-pane`	Float the focused tiled pane above the tiled panes, at the top-left cell and the size where it is drawn, each axis cut to 90% of the smallest pane area
`core:dock-pane`	Insert a floating pane into a tab's tiled layout
`core:move-floating-pane`	Move a floating pane to a top-left cell on one client's screen
`core:pin-pane`	Pin the focused floating pane at its top-left cell on the issuing client's screen
`core:unpin-pane`	Unpin the focused floating pane on the issuing client's screen
`core:toggle-pane-pinned`	Pin the focused floating pane at its top-left cell on the issuing client's screen, or unpin it when it is pinned there
`core:minimize-pane`	Minimize the focused floating pane on the issuing client's screen
`core:restore-pane`	Restore a minimized floating pane on one client's screen and focus it
`core:minimize-all-floating-panes`	Minimize every floating pane the issuing client shows
`core:restore-all-floating-panes`	Restore every floating pane the issuing client minimized, and focus the last one
`core:toggle-minimize-all-floating-panes`	Minimize every floating pane the issuing client shows, or restore every one when it shows none
`core:focus-next-floating-pane`	Show and focus the floating pane after the focused one, in the order the panes became floating
`core:focus-previous-floating-pane`	Show and focus the floating pane before the focused one, in the order the panes became floating

Pane move actions

Action	Result
`core:begin-pane-placement`	Open pane placement mode for the focused pane
`core:select-pane-target-left`	Select the visible pane target to the left in placement mode
`core:select-pane-target-down`	Select the visible pane target below in placement mode
`core:select-pane-target-up`	Select the visible pane target above in placement mode
`core:select-pane-target-right`	Select the visible pane target to the right in placement mode
`core:select-pane-insertion-left`	Select the left insertion edge in placement mode
`core:select-pane-insertion-down`	Select the lower insertion edge in placement mode
`core:select-pane-insertion-up`	Select the upper insertion edge in placement mode
`core:select-pane-insertion-right`	Select the right insertion edge in placement mode
`core:cycle-pane-placement-span`	Cycle the available insertion spans in placement mode
`core:toggle-pane-placement-stack`	Switch the selected target between beside a pane or stack and into that stack
`core:select-next-placement-tab`	Preview the next visible tab in placement mode
`core:select-previous-placement-tab`	Preview the previous visible tab in placement mode
`core:confirm-pane-placement`	Submit the selected pane placement in placement mode
`core:cancel-pane-placement`	Discard the pane placement and return to the base input mode
`core:begin-tiled-pane-placement`	Open pane placement mode for the focused pane of the active tab
`core:begin-floating-pane-move`	Open floating pane move mode on a floating pane this client shows
`core:confirm-pane-move-choice`	Open the move mode for the kind of the focused pane in the pane move chooser
`core:cancel-pane-move-choice`	Close the pane move chooser and return to the base input mode
`core:move-floating-pane-left`	Move the selected floating pane one cell left in floating pane move mode
`core:move-floating-pane-down`	Move the selected floating pane one cell down in floating pane move mode
`core:move-floating-pane-up`	Move the selected floating pane one cell up in floating pane move mode
`core:move-floating-pane-right`	Move the selected floating pane one cell right in floating pane move mode
`core:select-next-floating-pane`	Select and focus the next floating pane, in the order the panes became floating, in floating pane move mode
`core:select-previous-floating-pane`	Select and focus the previous floating pane, in the order the panes became floating, in floating pane move mode
`core:confirm-floating-pane-move`	Move the selected floating pane to its draft in floating pane move mode
`core:cancel-floating-pane-move`	Discard the floating pane draft and return to the base input mode

Floating pane tray actions

Action	Result
`core:toggle-floating-pane-tray`	Open the floating pane tray under the tabline's tray button, or close it when it is open
`core:close-floating-pane-tray`	Close the floating pane tray and return to the base input mode
`core:select-tray-tile-left`	Select the tile to the left in the floating pane tray
`core:select-tray-tile-down`	Select the tile below in the floating pane tray
`core:select-tray-tile-up`	Select the tile above in the floating pane tray
`core:select-tray-tile-right`	Select the tile to the right in the floating pane tray
`core:activate-selected-tray-tile`	Minimize or restore the selected tile's floating pane on this client's screen; on the + new tile, close the tray and create a floating pane

Notification center actions

Action	Result
`core:toggle-notification-center`	Open this client's notification center on the right side, or close it when it is open
`core:close-notification-center`	Close the notification center and keep its entries
`core:select-newer-notification`	Select the notification card above the selected one in the notification center
`core:select-older-notification`	Select the notification card below the selected one in the notification center
`core:dismiss-selected-notification`	Remove the selected notification card from this client's notification center
`core:clear-notifications`	Remove every entry from this client's notification center and close it

Tab, session, and client actions

Action	Result
`core:new-tab`	Create a new tab
`core:close-tab`	Close the focused tab
`core:focus-tab`	Switch the issuing client's view to a specific tab
`core:next-tab`	Switch the issuing client's view to the next tab
`core:previous-tab`	Switch the issuing client's view to the previous tab
`core:move-tab`	Move the focused tab to a new index
`core:lock`	Enable pass-through lock mode for the issuing client
`core:unlock`	Disable pass-through lock mode for the issuing client
`core:toggle-lock`	Toggle pass-through lock mode for the issuing client
`core:mouse-select`	Toggle grabbing the mouse for text selection, so a drag highlights in koshi even over a program that asked for the mouse
`core:quit`	Leave the session, ending it when auto-close-session is on and no other client stays

core:quit detaches this terminal. It ends the session only when auto-close-session #true and no other terminal is attached. There is no action that ends a session outright — use koshi kill-session.

Binding rules

Write the namespace: core:new-tab, not new-tab. Bindings accept no action arguments. Fixed choices belong in the action name; open values such as a pane id, tab index, or text belong to the CLI.

These actions need values that only their CLI command supplies, so a key bound to one never fires, and koshi keys validate and koshi keys conflicts warn about it: core:run, core:resize-pane, core:focus-pane, core:move-pane, core:place-pane, core:dock-pane, core:move-floating-pane, core:restore-pane, core:scroll-pane, core:write-to-pane, core:focus-tab, and core:move-tab. koshi actions run refuses them too and names the command to use, such as koshi focus-tab.

keybinding.kdl

version 2

mode "normal" {
    bind "<A-h>" "core:focus-pane-left"
    bind "<A-l>" "core:focus-pane-right"
}

Actions