# Keybindings URL: https://tuios.dev/docs/keybindings > Every default key in TUIOS for window mode, terminal mode, prefix commands, copy mode and the mouse, grouped by the config section that owns it. TUIOS has two modes. **Window mode** is for managing panes. **Terminal mode** sends your keys to the focused pane. A new session starts in window mode. The leader key is Ctrl+B. Press it, release it, then press a command key. The leader works in both modes. Every table on this page names the config section that holds the binding and the action name to use in it. Every action is rebindable. See [Customizing](https://tuios.dev/docs/keybindings#customizing) at the end. **Try it live:** [Learn tuios](https://tuios.dev/learn) has you press these keys in the real app, in your browser. [Free play](https://tuios.dev/learn?t=play) has a cheat sheet you can click. > **Check your own bindings** > > This page lists the defaults. `tuios keybinds list`, `tuios keybinds explain ` and the keybind manager (Ctrl+B k) show what is bound on your machine. ## Modes Section: `[keybindings.mode_control]`. These keys work in window mode. | Key | Action | Does | | -------- | --------------------- | ----------------------------------------------------- | | i, Enter | `enter_terminal_mode` | Enter terminal mode | | Esc | `enter_window_mode` | Enter window mode | | ? | `toggle_help` | Toggle the help overlay | | , | `open_settings` | Open the settings page | | q | `quit` | Quit | | none | `hold_window_mode` | Window mode while the key is held. Unbound by default | To leave terminal mode, press Ctrl+B Esc, or the direct key from [Terminal mode](https://tuios.dev/docs/keybindings#terminal-mode). `hold_window_mode` needs a terminal that speaks the Kitty keyboard protocol (Ghostty, kitty, WezTerm, foot, Alacritty), because only that protocol reports key releases. Bind it to an ordinary spare key, such as an unused function key from `f1` to `f12`. Binding a modifier such as `leftalt` also works, but then every keystroke in the session arrives as an escape code. ## Window mode ### Windows Section: `[keybindings.window_management]`. | Key | Action | Does | | ----------- | -------------------------------------- | ----------------------------------------------------------- | | n | `new_window` | New window | | N | `new_session` | New session. Asks which machine when there is more than one | | w, x | `close_window` | Close the focused window | | r | `rename_window` | Rename the focused window | | m | `minimize_window` | Minimize the focused window | | M | `restore_all` | Restore all minimized windows | | z | `toggle_zoom` | Zoom the focused window, or unzoom it | | Tab | `next_window` | Focus the next window | | Shift+Tab | `prev_window` | Focus the previous window | | 1 to 9 | `select_window_1` to `select_window_9` | Focus a window by number | | c | `copy_selection` | Copy the mouse selection | | s | `focus_sidebar` | Give the keyboard to the session rail | | S | `start_screensaver` | Start the screen saver now | | Alt+Shift+N | `next_session` | Next session | | Alt+Shift+P | `prev_session` | Previous session | Section `[keybindings.restore_minimized]` restores one minimized window by position: | Key | Action | | -------------------------------- | ---------------------------------------------- | | Shift+1 to Shift+9 (also ! to () | `restore_minimized_1` to `restore_minimized_9` | Section `[keybindings.system]` has one binding: b is `toggle_spotlight`, which lights one part of the screen and dims the rest. See the `[spotlight]` options in [Configuration](https://tuios.dev/docs/configuration#the-spotlight-table). ### Workspaces Section: `[keybindings.workspaces]`. There are nine workspaces. The modifier is Option on macOS and Alt elsewhere. | Key | Action | Does | | -------------------------- | -------------------------------------------- | ------------------------------------------- | | Alt+1 to Alt+9 | `switch_workspace_1` to `switch_workspace_9` | Show a workspace | | Alt+Shift+1 to Alt+Shift+9 | `move_and_follow_1` to `move_and_follow_9` | Move the focused window there and follow it | ### Layout and snapping Section: `[keybindings.layout]`. | Key | Action | Does | | --------- | --------------------------- | ------------------------------------------------------------- | | t | `toggle_tiling` | Turn tiling on or off | | h | `snap_left` | Snap to the left half. In tiling, focus left | | l | `snap_right` | Snap to the right half. In tiling, focus right | | f | `snap_fullscreen` | Fill the screen | | u | `unsnap` | Restore the size before the snap | | H, Ctrl+← | `swap_left` | Swap with the window to the left | | L, Ctrl+→ | `swap_right` | Swap with the window to the right | | K, Ctrl+↑ | `swap_up` | Swap with the window above | | J, Ctrl+↓ | `swap_down` | Swap with the window below | | < | `resize_master_shrink` | Narrow the master area | | > | `resize_master_grow` | Widen the master area | | { | `resize_height_shrink` | Shorten the focused window from the bottom edge | | } | `resize_height_grow` | Lengthen the focused window from the bottom edge | | . | `resize_master_grow_left` | Widen the master area from the left edge | | \[ | `resize_height_shrink_top` | Shorten the focused window from the top edge | | ] | `resize_height_grow_top` | Lengthen the focused window from the top edge | | none | `resize_master_shrink_left` | Narrow the master area from the left edge. Unbound by default | `resize_master_shrink_left` has no default because , opens settings. Bind it to a free key if you want it. Corner snapping is on the [layout prefix](https://tuios.dev/docs/keybindings#layout-prefix), not on the bare digits. ### BSP splits Also in `[keybindings.layout]`. See [BSP Tiling](https://tuios.dev/docs/bsp-tiling). | Key | Action | Does | | ----------------- | --------------------------------------------------------------------- | ------------------------------------- | | - | `split_horizontal` | Split the focused pane top and bottom | | \|, \\ | `split_vertical` | Split the focused pane left and right | | R | `rotate_split` | Flip the split direction | | = | `equalize_splits` | Reset every split ratio | | Alt+h / j / k / l | `preselect_left`, `preselect_down`, `preselect_up`, `preselect_right` | Choose where the next window opens | The preselect keys use Option on macOS. The prefix menu has its own copies of the four split actions, and rebinding one set does not change the other. ## Terminal mode Section: `[keybindings.terminal_mode]`. These keys work in terminal mode with no prefix. Everything else goes to the pane. > > | Key | Action | Does | > > | --------------------- | ----------------------------------------------- | --------------------------------- | > > | Alt+n | `terminal_next_window` | Focus the next window | > > | Alt+p | `terminal_prev_window` | Focus the previous window | > > | Alt+Esc | `terminal_exit_mode` | Go to window mode | > > | Alt+arrows | `terminal_focus_left`, `_right`, `_up`, `_down` | Focus the pane in that direction | > > | Shift+↑ | `terminal_scroll_up` | Scroll into the pane's scrollback | > > | Shift+↓ | `terminal_scroll_down` | Scroll back toward live output | > > | Ctrl+Shift+V, Super+V | `terminal_paste_host` | Paste from the host clipboard | > > > | Key | Action | Does | > > | ----------------------- | ----------------------------------------------- | --------------------------------- | > > | Option+Tab, Alt+n | `terminal_next_window` | Focus the next window | > > | Option+Shift+Tab, Alt+p | `terminal_prev_window` | Focus the previous window | > > | Option+Esc | `terminal_exit_mode` | Go to window mode | > > | Alt+arrows | `terminal_focus_left`, `_right`, `_up`, `_down` | Focus the pane in that direction | > > | Shift+↑ | `terminal_scroll_up` | Scroll into the pane's scrollback | > > | Shift+↓ | `terminal_scroll_down` | Scroll back toward live output | > > | Ctrl+Shift+V, Super+V | `terminal_paste_host` | Paste from the host clipboard | > **Alt+Left and Alt+Right cost you word motions** > > Readline, fish and zsh use Alt+← and Alt+→ to move a word at a time. To give them back, run `tuios keybinds free alt+left` and `tuios keybinds free alt+right`. Ctrl+B then an arrow still moves focus. Plain Ctrl+V is not bound. It reaches the pane, so vim's visual block mode works. ## Global keys Section: `[keybindings.global]`. These keys work in window mode and terminal mode. | Key | Action | Does | | --------- | ----------------- | ------------------------ | | Ctrl+P | `command_palette` | Open the command palette | | Alt+Space | `launcher` | Open the app launcher | The **command palette** searches commands, sessions and windows. Start the query with `@` to filter panes by agent state (`@n` for needs input), or with `#` to search actions to rebind. The **app launcher** lists every executable on `$PATH`, ranked by use. Enter runs the selection in a new pane with no shell in between. Tab types the command into the focused shell instead, so you can add arguments. These two keys take Ctrl+P from fish and vim and Alt+Space from readline. Set an action to `[]` to give its key back. On macOS, Option+Space types a non-breaking space, so use Ctrl+B a for the launcher. ## Prefix commands Press Ctrl+B, then the key. Section: `[keybindings.prefix_mode]`. | Key | Action | Does | | ------------ | ----------------------------------------------- | ----------------------------------------------------------------------- | | c | `prefix_new_window` | New window | | x | `prefix_close_window` | Close the focused window | | r | `prefix_rename_window` | Rename the focused window | | n, Tab | `prefix_next_window` | Next window | | p, Shift+Tab | `prefix_prev_window` | Previous window | | 0 to 9 | `prefix_select_0` to `prefix_select_9` | Jump to a window | | arrows | `terminal_focus_left`, `_right`, `_up`, `_down` | Focus the pane in that direction | | ) | `next_session` | Next session | | ( | `prev_session` | Previous session | | Space | `prefix_toggle_tiling` | Turn tiling on or off | | z | `prefix_fullscreen` | Zoom the focused window | | - | `prefix_split_horizontal` | Split top and bottom | | \|, \\ | `prefix_split_vertical` | Split left and right | | R | `prefix_rotate_split` | Flip the split direction | | = | `prefix_equalize_splits` | Reset every split ratio | | \[ | `prefix_selection` | Enter [copy mode](https://tuios.dev/docs/keybindings#copy-mode) | | s | `prefix_scrollback` | Open the scrollback browser | | C | `prefix_screenshot` | Take a screenshot | | P | `prefix_command_palette` | Open the command palette | | a | `launcher` | Open the app launcher | | , | `prefix_settings` | Open the settings page | | k | `prefix_keybinds` | Open the keybind manager | | b | `prefix_toggle_sidebar` | Show or hide the session rail | | e | `prefix_explore` | Move the keyboard to the rail, or back | | S | `prefix_session_switcher` | Open the session switcher | | W | `prefix_workspace_switcher` | Open the workspace switcher | | j | `prefix_jump_notif` | Jump to the pane of the newest message | | M | `prefix_mail` | Open the agent mailbox | | t | `prefix_window` | [Window prefix](https://tuios.dev/docs/keybindings#window-prefix) | | m | `prefix_minimize` | [Minimize prefix](https://tuios.dev/docs/keybindings#minimize-prefix) | | w | `prefix_workspace` | [Workspace prefix](https://tuios.dev/docs/keybindings#workspace-prefix) | | L | `prefix_layout` | [Layout prefix](https://tuios.dev/docs/keybindings#layout-prefix) | | T | `prefix_tape` | [Tape prefix](https://tuios.dev/docs/keybindings#tape-prefix) | | D | `prefix_debug` | [Debug prefix](https://tuios.dev/docs/keybindings#debug-prefix) | | d | `prefix_detach` | Detach. The session keeps running | | X | `prefix_close_session` | Close the session and its panes | | Esc | `prefix_exit_mode` | Leave terminal mode. Never detaches | | q | `prefix_quit` | Quit. In a daemon session this kills the session | | ? | `prefix_help` | Toggle help | In terminal mode, pressing the leader twice sends one literal Ctrl+B to the pane. After a command worth repeating, such as an arrow, the prefix stays armed for 500 ms. Ctrl+B then ← ← ← moves three panes. Change this with `appearance.prefix_repeat_time`. `0` turns it off. ### Window prefix Ctrl+B t, then the key. Section: `[keybindings.window_prefix]`. | Key | Action | Does | | --------- | ---------------------- | ------------------------- | | n | `window_prefix_new` | New window | | x | `window_prefix_close` | Close the focused window | | r | `window_prefix_rename` | Rename the focused window | | Tab | `window_prefix_next` | Next window | | Shift+Tab | `window_prefix_prev` | Previous window | | t | `window_prefix_tiling` | Turn tiling on or off | | Esc | `window_prefix_cancel` | Cancel | ### Minimize prefix Ctrl+B m, then the key. Section: `[keybindings.minimize_prefix]`. | Key | Action | Does | | ------ | ---------------------------------------------------------- | -------------------------------------- | | m | `minimize_prefix_focused` | Minimize the focused window | | 1 to 9 | `minimize_prefix_restore_1` to `minimize_prefix_restore_9` | Restore a minimized window by position | | M | `minimize_prefix_restore_all` | Restore all minimized windows | | Esc | `minimize_prefix_cancel` | Cancel | ### Workspace prefix Ctrl+B w, then the key. Section: `[keybindings.workspace_prefix]`. | Key | Action | Does | | ------------------ | ---------------------------------------------------------- | ------------------------------------------- | | 1 to 9 | `workspace_prefix_switch_1` to `workspace_prefix_switch_9` | Show a workspace | | ! @ # $ % ^ & \* ( | `workspace_prefix_move_1` to `workspace_prefix_move_9` | Move the focused window there and follow it | | r | `workspace_prefix_rename` | Rename the current workspace | | Esc | `workspace_prefix_cancel` | Cancel | ### Layout prefix Ctrl+B L, then the key. Section: `[keybindings.layout_prefix]`. | Key | Action | Does | | ------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------- | | l | `layout_prefix_load` | Open the layout picker | | s | `layout_prefix_save` | Save the current layout as a template | | 1 to 4 | `snap_corner_1` to `snap_corner_4` | Snap to the top-left, top-right, bottom-left or bottom-right quarter. Floating mode only | | 5 to 9 | `resize_width_50` to `resize_width_90` | Set the focused window's width to 50% to 90% | | Shift+5 to Shift+9 | `resize_height_50` to `resize_height_90` | Set its height to 50% to 90% | | Esc | `layout_prefix_cancel` | Cancel | Actions `resize_width_10` to `resize_width_40` and `resize_height_10` to `resize_height_40` also exist, with no default key. Loading a layout moves the existing windows into place. It does not close any. Extra windows are minimized. `tuios layout` manages saved templates from the shell. ### Tape prefix Ctrl+B T, then the key. Section: `[keybindings.tape_prefix]`. See [Tape Recording](https://tuios.dev/docs/tape-recording). | Key | Action | Does | | --- | --------------------- | ----------------------------------------------- | | m | `tape_prefix_manager` | Open the tape manager | | r | `tape_prefix_record` | Start recording | | s | `tape_prefix_stop` | Stop recording | | t | `tape_prefix_review` | Review the project tape found in this directory | | Esc | `tape_prefix_cancel` | Cancel | While a tape plays, section `[keybindings.script]` is active: Ctrl+P is `script_pause` and pauses or resumes playback. ### Debug prefix Ctrl+B D, then the key. Section: `[keybindings.debug_prefix]`. | Key | Action | Does | | --- | ------------------------- | -------------------------------------------------------------- | | l | `debug_prefix_logs` | Toggle the log viewer | | c | `debug_prefix_cache` | Toggle style cache statistics | | k | `debug_prefix_showkeys` | Toggle the [showkeys](https://tuios.dev/docs/showkeys) overlay | | a | `debug_prefix_animations` | Toggle animations | | Esc | `debug_prefix_cancel` | Cancel | ## Session rail Section: `[keybindings.sidebar]`. Active while the rail has the keyboard: press s in window mode, or Ctrl+B e. | Key | Action | Does | | -------------- | -------------------- | ---------------------------------------------- | | j, ↓ | `cursor_down` | Move down | | k, ↑ | `cursor_up` | Move up | | g, Home | `first` | First row | | G, End | `last` | Last row | | l, → | `expand` | Expand the row | | h, ← | `collapse` | Collapse the row | | Enter | `activate` | Open the row | | J, Shift+↓ | `reorder_down` | Move the session or machine down | | K, Shift+↑ | `reorder_up` | Move the session or machine up | | Tab, Shift+Tab | `section` | Go to the next section | | 1 to 9 | `jump_1` to `jump_9` | Jump to a row by number | | n | `new_session` | New session | | t | `new_window` | New window | | r | `rename` | Rename the pane or session | | c | `accent` | Set the session's accent colour | | x | `kill` | Open the row's close menu | | m | `menu` | Open the row's menu | | i | `mail` | Open the mailbox for the pane under the cursor | | f | `agents_filter` | Filter the agents section | | o | `agents_sort` | Sort the agents section | | / | `palette` | Open the command palette | | < | `narrow` | Narrow the rail | | > | `widen` | Widen the rail | | ? | `help` | Show the rail's help | | Esc, s | `exit` | Give the keyboard back | When the cursor is on a row in the files section, section `[keybindings.sidebar_files]` answers first: | Key | Action | Does | | ----- | --------------------- | -------------------------------------------- | | Enter | `file_open` | Open the folder, or copy the file's path | | a | `file_create` | New file. End the name with `/` for a folder | | r | `file_rename` | Rename | | d | `file_delete` | Delete to the trash | | D | `file_delete_forever` | Delete with no trash | | y | `file_copy` | Copy | | x | `file_cut` | Cut | | p | `file_paste` | Paste into this folder | See [The files section](https://tuios.dev/docs/configuration#the-files-section). ## Copy mode Press Ctrl+B \[ to enter copy mode. It moves a cursor through the scrollback with vim keys. These keys are fixed and are not in the config. Put a count before a motion to repeat it: `10j`, `5w`. | Keys | Does | | ---------------------------- | -------------------------------------------- | | h j k l, arrows | Move the cursor | | w b e | Next word, previous word, end of word | | W B E | The same, for space-separated words | | 0 ^ $ | Line start, first non-blank, line end | | H M L | Top, middle and bottom of the screen | | gg, G | Top of the scrollback, bottom (live output) | | `{n}G` | Go to line `n` | | { } | Previous and next paragraph | | % | Matching bracket | | Ctrl+U / Ctrl+D | Half page up, down | | Ctrl+B / Ctrl+F, PgUp / PgDn | Full page up, down | | f F t T then a character | Find a character on the line | | ; , | Repeat the character search, forward or back | | / ? | Search forward, backward | | n N | Next match, previous match | | Ctrl+L | Clear search highlights | | v V | Start a character or line selection | | y, c | Copy the selection to the clipboard | | i | Leave copy mode and go to terminal mode | | q, Esc | Leave copy mode | The scrollback browser (Ctrl+B s) is a different tool. It lists past commands by their prompt marks, for shells that emit OSC 133. ## Mouse | Gesture | Does | | --------------------------- | ------------------------------------------------------------------------------ | | Click a pane | Focus it. In window mode it also starts typing, per `appearance.click_to_type` | | Drag a title bar | Move the window. In tiling, swap it with the pane you drop it on | | Alt + drag | Move the window from anywhere inside it (`appearance.alt_drag`) | | Right-drag | Resize the window | | Right-click | In window mode, open the menu for the pane, the dock or the desktop | | Shift or Ctrl + right-click | Open the pane menu even when the program in the pane uses the mouse | | Title bar buttons | Minimize, zoom or close | | Click a dock item | Restore a minimized window | | Wheel up | Enter copy mode and scroll, when the program is not using the mouse | | Drag the right border | Scroll with the scrollbar | | Shift + click a link | Open it. `appearance.links` decides what counts as a link | In floating mode, drop a window on a screen edge to snap it: the left or right edge for a half, a corner for a quarter, the top center for the full screen. In copy mode, a click moves the cursor and a drag selects. Dragging past the top or bottom of the pane scrolls. ## Customizing Bindings live in 19 sections under `[keybindings]` in `config.toml`. Each action takes a list of keys. ```toml [keybindings] leader_key = "ctrl+a" [keybindings.window_management] new_window = ["n", "ctrl+t"] close_window = [] # unbind: the key goes back to the pane ``` An empty list and a missing line are different. A missing action gets its default back at the next load. An empty list stays empty. Key syntax and every section are on the [Configuration](https://tuios.dev/docs/configuration#keybindings) page. Inspect and change bindings from the shell: ```bash tuios keybinds list # the main tables tuios keybinds doctor # conflicts, and keys taken from the pane tuios keybinds explain alt+left # everything one key does tuios keybinds unbind close_window w # take one key off one action tuios keybinds free alt+left # take a key off every action ``` `doctor` tags each finding with its evidence: `certain` comes from TUIOS routing, `observed` from the live pane, `reference` from a list of common program defaults. `doctor` and `explain` take `--json` and `--guest `. The **keybind manager** (Ctrl+B k) shows the same analysis in four tabs: Bindings, Conflicts, Guests and Record. Record captures the next key you press. On a binding, Ctrl+D removes it and Ctrl+X takes its key off every action. > **Keybinding edits need a new client** > > The config file reloads on save, but only `leader_key` among the keybindings. After editing other bindings, detach and attach again, or restart TUIOS. Changes made with the keybind manager apply at once. > **keybinds list-custom is partial** > > `tuios keybinds list-custom` compares 9 of the 19 sections: `window_management`, `workspaces`, `layout`, `mode_control`, `system`, `prefix_mode`, `window_prefix`, `minimize_prefix` and `workspace_prefix`. It does not report `leader_key`. Use `tuios keybinds doctor` or read the file for the rest. ## macOS macOS treats Option as a compose key unless the terminal says otherwise. An Option chord then arrives as a character. TUIOS maps most of those characters back to the chord, which is why Option+1 to Option+9 work with no setup. Two kinds cannot be recovered: - **Dead keys.** Option+e, i, n, u and \` send nothing until a second key. Alt+n (next window in terminal mode) takes two presses. - **Rewritten chords.** Many terminals send Option+← and Option+→ as readline word motions, with no sign that an arrow was pressed. To fix both, turn on your terminal's Option-as-Alt setting: | Terminal | Setting | | ------------ | ------------------------------------------------------- | | Ghostty | `macos-option-as-alt = true` | | Terminal.app | Settings > Profiles > Keyboard > Use Option as Meta Key | | iTerm2 | Settings > Profiles > Keys > Left Option key: Esc+ | | kitty | `macos_option_as_alt yes` | | WezTerm | `send_composed_key_when_left_alt_is_pressed = false` | | Alacritty | `option_as_alt = "Both"` under `[window]` | | VS Code | `terminal.integrated.macOptionIsMeta` | Ghostty also needs `keybind = alt+left=unbind` and `keybind = alt+right=unbind`, because its own keybinds rewrite those arrows first. The prefix works on every terminal with no setup. Ctrl+B then an arrow, n, p, (, ), a or a digit covers every navigation command. Command chords never reach a terminal program. macOS sends them to the menu bar. ## Related *[An interactive figure goes here. Open the page to use it.](https://tuios.dev/docs/keybindings)*