# Koshi 0.6.0 — Actions (/docs/v0.6/keybindings/actions)



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

```bash
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 [#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 [#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 [#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 [#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 [#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 [#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                                     |

<Callout>
  `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`.
</Callout>

## Binding rules [#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`.

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

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